feat(quick-dev): improve checkpoint 1 UX

[alexeyv]

Summary

• Display spec file path as clickable CWD-relative link alongside the checkpoint summary (moved from post-approval to presentation time)
• Add note informing users they can open the spec externally with any tool (party mode, advanced elicitation, code review, etc.) before approving
• On approval, re-read spec from disk and acknowledge any external edits before proceeding; HALT if file missing

Test plan

• Run quick-dev through step-02 and verify the spec path appears clickable in the summary
• Verify the external editing note is displayed below the options
• Edit the spec externally during the HALT, approve, and confirm external changes are acknowledged
• Approve without external edits and confirm no change mention appears

[augmentcode]

🤖 Augment PR Summary

Summary: Improves Quick-Dev Step 2 Checkpoint 1 by showing the spec path as a clickable CWD-relative link and adding guidance about externally editing the spec before approval.
Behavior: On approval, re-reads the spec from disk, acknowledges any external edits, and halts if the file is missing before proceeding to implementation.

_{🤖 Was this summary useful? React with 👍 or 👎}

[augmentcode]

Review completed. 2 suggestions posted.

Comment augment review to trigger a new review at any time.

[alexeyv]

Triage complete: 2 findings — FIX: 2, DISMISS: 0, DEFER: 0

• F1 [LOW] Note ordering ambiguity vs [A]/[E] menu in step-02-plan.md — FIX
• F2 [MEDIUM] Missing-file HALT followed by spec_file mutations in A flow — FIX

Both fixes in commit 3942a51.

[coderabbitai]

📝 Walkthrough

Walkthrough

The PR updates the bmad-quick-dev workflow to treat draft-status spec files as resumable artifacts, routes them to step-02, removes the {wipFile} singleton path definition, and modifies step-02's approval flow to write and update specs in {spec_file} with enhanced disk validation.

Changes

Cohort / File(s)	Summary
Workflow Routing and Configuration src/bmm-skills/4-implementation/bmad-quick-dev/step-01-clarify-and-route.md, src/bmm-skills/4-implementation/bmad-quick-dev/workflow.md	Added routing logic for draft-status specs as resumable artifacts with early-exit to ./step-02-plan.md; updated artifact selection menu to include and list draft as resumable; removed wipFile path definition and renumbered workflow sections.
Spec Approval and File Handling src/bmm-skills/4-implementation/bmad-quick-dev/step-02-plan.md	Changed spec output destination from {wipFile} to {spec_file}, updated checkpoint to present CWD-relative {spec_file} path, and implemented new approval flow that re-reads spec from disk, validates file presence, detects external changes, and sets status to ready-for-dev with frozen-after-approval locking.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• refactor(quick-dev): eliminate spec-wip.md singleton #2214: Implements identical changes—removes wipFile singleton, treats draft as resumable state, and updates step-02 to write specs to spec_file rather than using a wip file.
• feat(quick-dev): clickable spec link at step-02 checkpoint and CWD-relative path convention #2049: Modifies step-02 checkpoint to present CWD-relative clickable spec path and alters approval behavior related to spec file handling.
• refactor(quick-dev): replace unconditional artifact scan with intent cascade #2105: Refactors step-01 routing logic with tiered intent cascade, overlapping with this PR's intent resolution and early-exit behavior updates.

Suggested reviewers

• bmadcode

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'feat(quick-dev): improve checkpoint 1 UX' clearly summarizes the main change—improving user experience at checkpoint 1 in the quick-dev workflow, which aligns with the primary objective of adding clickable spec paths, external-editing notes, and change detection.
Description check	✅ Passed	The description is directly related to the changeset, detailing specific UX improvements (clickable spec path, external editing note, change detection on approval) and providing a test plan that aligns with the file modifications in step-02-plan.md.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/checkpoint-ux

⚔️ Resolve merge conflicts

• Resolve merge conflict in branch feat/checkpoint-ux

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

🧹 Nitpick comments (1)

src/bmm-skills/4-implementation/bmad-quick-dev/step-02-plan.md (1)

34-36: Consider adding a context-loss fallback to the change-detection instruction.

The re-read-and-compare logic is sound for typical sessions: the 1600-token spec cap (line 18) and distilled subagent summaries (line 14) prevent context snowballing, and the explicit disk re-read (line 34) allows the agent to detect external edits. However, in edge cases where a long session exhausts context before the approval checkpoint, the agent may lose the ability to recall the original spec content accurately.

The current instruction assumes "Compare the content to what you wrote" will succeed. A minor addition—such as "If you cannot recall the original content clearly, inform the user and ask them to confirm any changes manually"—would provide a graceful fallback without disrupting the normal flow.

This is a defensive improvement aligned with the defensive "do not write, do not proceed" wording on the missing-file branch and would strengthen robustness in extended sessions.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/bmm-skills/4-implementation/bmad-quick-dev/step-02-plan.md` around lines
34 - 36, Add a context-loss fallback to the re-read-and-compare step: when
re-reading `{spec_file}` in the block that currently says "Compare the content
to what you wrote", if the agent cannot confidently recall the original content
(due to context limits), it should notify the user, present the current file
contents and a short explanation that it cannot determine exact prior content,
and ask the user to confirm or specify what changed before proceeding; only
after explicit user confirmation should the agent set status `ready-for-dev` in
`{spec_file}` and lock everything inside `<frozen-after-approval>` and continue
to Step 3.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In `@src/bmm-skills/4-implementation/bmad-quick-dev/step-02-plan.md`:
- Around line 34-36: Add a context-loss fallback to the re-read-and-compare
step: when re-reading `{spec_file}` in the block that currently says "Compare
the content to what you wrote", if the agent cannot confidently recall the
original content (due to context limits), it should notify the user, present the
current file contents and a short explanation that it cannot determine exact
prior content, and ask the user to confirm or specify what changed before
proceeding; only after explicit user confirmation should the agent set status
`ready-for-dev` in `{spec_file}` and lock everything inside
`<frozen-after-approval>` and continue to Step 3.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 633808fd-fad0-4bfb-a9e0-c3e973b37b28

📥 Commits

Reviewing files that changed from the base of the PR and between 9ca0316 and 3942a51.

📒 Files selected for processing (3)

• src/bmm-skills/4-implementation/bmad-quick-dev/step-01-clarify-and-route.md
• src/bmm-skills/4-implementation/bmad-quick-dev/step-02-plan.md
• src/bmm-skills/4-implementation/bmad-quick-dev/workflow.md