phase-tracking

Update the project progress-tracking doc based on changes that happened in the current conversation.

The progress doc can have any name — common examples: CLAUDE.md, ROADMAP.md, TODO.md, progress.md, or a "Development plan & progress" section in the main README. Stage 0 step 1 is always confirming with the user which doc to update; if the project has no progress doc yet, prompt the user to create one first (this skill does not fabricate content for the project).

When to use

• The user says "update progress", "milestone status changed", "update CLAUDE.md", "log this progress".
• After a feature, milestone, or tech-stack change wraps up.

When NOT to use

• Writing a new roadmap from scratch — this skill updates an existing progress doc; it does not invent content.
• Recording a single commit's worth of code change with no progress implications — just write a normal commit message.

Input: no parameters. Changes are extracted automatically from the current conversation context.

Steps

1. Locate the progress doc Search project root, docs/, and other common locations for a progress-tracking doc. If multiple exist, ask the user to pick one.

2. Collect change information

   The change scope is determined by crossing two dimensions:

   Dimension 1: Conversation context — review what was discussed in the current conversation; this is the source for judging "which changes are meaningful enough to record".

   Dimension 2: Actual git changes — run git diff, git diff --staged, and git status to capture the real additions / deletions / modifications in the working tree. This anchors the change scope in reality, not memory or guesswork.

   Combine the two: use conversation context to understand the semantics and importance of each change, and use git changes to confirm what actually changed. Do not presuppose a fixed checklist of change types.

3. Generate the update proposal

   Organize the changes and produce a structured update proposal that contains:

   • Change summary: one sentence describing the theme of this round.
   • Sections needing update: list which sections of the progress doc need editing.
   • Concrete edits: for each section, show a diff-style preview:

     ## Development plan & progress
     
     - old: Stage 2 — User authentication module    ○ todo
     + new: Stage 2 — User authentication module    ✅ done (2026-06-12)

   • Sections not needing update: explicitly list the parts that do not need editing, so the user can confirm nothing was missed.

   If the current conversation produced no changes worth recording, tell the user "no changes to record" and stop.

   Status markers: follow the target doc's existing status convention (icons / text / color tags — match what the doc already uses). If the doc has no established convention, common schemes include:

   • ✅ done / 🔨 in progress / ○ todo (icon style)
   • [done] / [wip] / [todo] (tag style)
   • 0–100% progress percentage

   How to judge "done": prefer the user's own description. If the user said "implemented X" but did not say "completed X", default to "in progress". Only mark "done" when the user explicitly says it is complete.

4. Wait for user confirmation

   Use the AskUserQuestion tool to present the proposal and ask:

   • Confirm update
   • Adjust content (user describes what to change)
   • Cancel

   Wait for explicit confirmation before proceeding.

5. Apply the update

   After confirmation, read the target progress doc and use the Edit tool to apply the updates.

6. Confirm completion

   Briefly report which sections were updated.

Guardrails (reasoned, not absolute)

• Only update parts of the progress doc that directly correspond to changes in this conversation — keeps the diff minimal and reviewable.
• Do not refactor or rewrite unrelated sections — the user's existing structure and wording should be preserved.
• Match the existing format style (status markers, indentation, list style) — consistency makes the doc scannable.
• Update tech-stack version numbers only when the user explicitly upgraded a dependency — silent version bumps make history misleading.
• If a change was already recorded in a separate spec / ADR, the progress doc should only update its index description, not duplicate the content.
• Do not delete content the user added by hand — preserving manual additions is part of trust.