fix(quick-dev): make file path references clickable

[alexeyv]

Summary

• Spec-file links (Review Order) switched from broken /workspace-root-relative format to spec-file-relative paths (../../path/to/file.ts#L42) — clickable in VS Code
• Terminal output paths now explicitly require CWD-relative format with :line notation for terminal clickability
• Applied across step-05-present.md, step-oneshot.md, and step-03-implement.md

Test plan

• Run quick-dev workflow end-to-end; verify Review Order links in the spec file are Ctrl+clickable in VS Code
• Verify terminal output file paths are clickable in terminal emulator
• Confirm no changes to review order structure, concern grouping, or framing rules

[coderabbitai]

📝 Walkthrough

Walkthrough

Documentation updates to path formatting conventions across the quick-dev skill implementation steps. Changes mandate CWD-relative paths with :line notation for terminal/conversation output and spec-file-relative markdown links without leading slashes for internal references.

Changes

Cohort / File(s)	Summary
Path Formatting Rules src/bmm-skills/4-implementation/bmad-quick-dev/step-03-implement.md, src/bmm-skills/4-implementation/bmad-quick-dev/step-05-present.md, src/bmm-skills/4-implementation/bmad-quick-dev/step-oneshot.md	Updated path formatting conventions to use CWD-relative paths with :line notation for terminal clickability (e.g., src/path/file.ts:42) and spec-file-relative markdown links without leading /. Added explicit path formatting rule to Step 3 and updated Suggested Review Order and file listing examples in Steps 5 and oneshot.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related PRs

• bmad-code-org/BMAD-METHOD#2039: Modifies link/path formatting in Step 5 "Present" flow with different approach (vscode:// URIs vs. CWD-relative :line paths)
• bmad-code-org/BMAD-METHOD#2033: Directly related update to step-05-present requiring clickable path:line references and spec link formatting
• bmad-code-org/BMAD-METHOD#1997: Modifies intra-skill file path conventions to use relative paths and remove project-root prefixes in step/spec links

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main change: making file path references clickable across multiple documentation files by updating path formatting conventions.
Description check	✅ Passed	The description is directly related to the changeset, explaining the rationale behind switching from broken workspace-root-relative paths to spec-file-relative and CWD-relative formats for clickability.
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 fix-review-order-links

---

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]

Actionable comments posted: 1

🧹 Nitpick comments (2)

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

25-25: Optional wording nit: capitalize “Markdown”.

Pure readability/terminology consistency tweak.

Proposed wording tweak

-5. **Every code reference is a clickable spec-file-relative link.** Compute each link target as a relative path from `{spec_file}`'s directory to the changed file. Format each stop as a markdown link: `[short-name:line](../../path/to/file.ts#L42)`. Use a `#L` line anchor. Use the file's basename (or shortest unambiguous suffix) plus line number as the link text. The relative path must be dynamically derived — never hardcode the depth.
+5. **Every code reference is a clickable spec-file-relative link.** Compute each link target as a relative path from `{spec_file}`'s directory to the changed file. Format each stop as a Markdown link: `[short-name:line](../../path/to/file.ts#L42)`. Use a `#L` line anchor. Use the file's basename (or shortest unambiguous suffix) plus line number as the link text. The relative path must be dynamically derived — never hardcode the depth.

🤖 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-05-present.md` at line
25, Minor wording nit: capitalize the word “Markdown” in the sentence that
begins "Every code reference is a clickable spec-file-relative link." Update the
wording in src/bmm-skills/4-implementation/bmad-quick-dev/step-05-present.md so
the phrase uses "Markdown" (capital M) wherever it currently appears lowercase
(e.g., in the instruction about formatting stops as a markdown link and any
occurrences near `{spec_file}`).

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

29-29: Capitalize “Markdown” for consistency in instruction text.

Tiny wording polish only; keeps terminology consistent with other docs and tooling references.

Proposed wording tweak

-**Path formatting rule:** Any markdown links written into `{spec_file}` must use paths relative to `{spec_file}`'s directory so they are clickable in VS Code. Any file paths displayed in terminal/conversation output must use CWD-relative format with `:line` notation (e.g., `src/path/file.ts:42`) for terminal clickability. No leading `/` in either case.
+**Path formatting rule:** Any Markdown links written into `{spec_file}` must use paths relative to `{spec_file}`'s directory so they are clickable in VS Code. Any file paths displayed in terminal/conversation output must use CWD-relative format with `:line` notation (e.g., `src/path/file.ts:42`) for terminal clickability. No leading `/` in either case.

🤖 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-03-implement.md` at line
29, The instruction text in step-03-implement.md uses lowercase “markdown” and
should be capitalized for consistency; update the Path formatting rule sentence
so the word “Markdown” is capitalized (e.g., change “Any markdown links” to “Any
Markdown links”) while preserving the rest of the wording and examples (the
CWD-relative `:line` notation and no leading `/` requirements) so behavior and
examples remain unchanged.

🤖 Prompt for all review comments with AI agents

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

Inline comments:
In `@src/bmm-skills/4-implementation/bmad-quick-dev/step-oneshot.md`:
- Line 43: Update the "List of files changed..." example in step-oneshot.md to
include the enforced ":line" suffix so paths follow the same clickable format
used in step-03-implement.md and step-05-present.md; find the line starting with
"List of files changed with one-line descriptions." and change the example path
entries to CWD-relative paths that end with ":line" (e.g.,
`src/path/file.ts:line`) ensuring every listed path includes the ":line" token
for consistency.

---

Nitpick comments:
In `@src/bmm-skills/4-implementation/bmad-quick-dev/step-03-implement.md`:
- Line 29: The instruction text in step-03-implement.md uses lowercase
“markdown” and should be capitalized for consistency; update the Path formatting
rule sentence so the word “Markdown” is capitalized (e.g., change “Any markdown
links” to “Any Markdown links”) while preserving the rest of the wording and
examples (the CWD-relative `:line` notation and no leading `/` requirements) so
behavior and examples remain unchanged.

In `@src/bmm-skills/4-implementation/bmad-quick-dev/step-05-present.md`:
- Line 25: Minor wording nit: capitalize the word “Markdown” in the sentence
that begins "Every code reference is a clickable spec-file-relative link."
Update the wording in
src/bmm-skills/4-implementation/bmad-quick-dev/step-05-present.md so the phrase
uses "Markdown" (capital M) wherever it currently appears lowercase (e.g., in
the instruction about formatting stops as a markdown link and any occurrences
near `{spec_file}`).

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: e612cdd1-cff4-4aa3-a836-d076247653e2

📥 Commits

Reviewing files that changed from the base of the PR and between 93a1e1d and ca32c0a.

📒 Files selected for processing (3)

• src/bmm-skills/4-implementation/bmad-quick-dev/step-03-implement.md
• src/bmm-skills/4-implementation/bmad-quick-dev/step-05-present.md
• src/bmm-skills/4-implementation/bmad-quick-dev/step-oneshot.md

[augmentcode]

🤖 Augment PR Summary

Summary: Updates the bmad-quick-dev step docs to make file references reliably clickable in VS Code and terminal output.
Changes: Switches Suggested Review Order links from leading-/ workspace-root paths to spec-file-relative link targets, and clarifies that terminal/conversation paths should be CWD-relative using path:line (no leading /) across the implement/present/oneshot steps.

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

[augmentcode]

Review completed. No suggestions at this time.

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