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

Spec-file links use paths relative to the spec file's
directory (clickable in VS Code). Terminal output paths
use CWD-relative format for terminal clickability.
This commit is contained in:
Alex Verkhovsky 2026-03-21 01:33:52 -06:00
parent 93a1e1dc46
commit ca32c0aa65
3 changed files with 10 additions and 6 deletions

View File

@ -26,6 +26,8 @@ Change `{spec_file}` status to `in-progress` in the frontmatter before starting
Hand `{spec_file}` to a sub-agent/task and let it implement. If no sub-agents are available, implement directly.
**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.
## NEXT
Read fully and follow `./step-04-review.md`

View File

@ -22,7 +22,7 @@ Build the trail as an ordered sequence of **stops** — clickable `path:line` re
2. **Lead with the entry point** — the single highest-leverage file:line a reviewer should look at first to grasp the design intent.
3. **Inside each concern**, order stops from most important / architecturally interesting to supporting. Lightly bias toward higher-risk or boundary-crossing stops.
4. **End with peripherals** — tests, config, types, and other supporting changes come last.
5. **Every code reference is a clickable workspace-relative link** (project-root-relative for clickability in the editor). Format each stop as a markdown link: `[short-name:line](/project-root-relative/path/to/file.ts#L42)`. The link target uses a leading `/` (workspace root) with a `#L` line anchor. Use the file's basename (or shortest unambiguous suffix) plus line number as the link text.
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.
6. **Each stop gets one ultra-concise line of framing** (≤15 words) — why this approach was chosen here and what it achieves in the context of the change. No paragraphs.
Format each stop as framing first, link on the next indented line:
@ -33,17 +33,19 @@ Format each stop as framing first, link on the next indented line:
**{Concern name}**
- {one-line framing}
[`file.ts:42`](/src/path/to/file.ts#L42)
[`file.ts:42`](../../src/path/to/file.ts#L42)
- {one-line framing}
[`other.ts:17`](/src/path/to/other.ts#L17)
[`other.ts:17`](../../src/path/to/other.ts#L17)
**{Next concern}**
- {one-line framing}
[`file.ts:88`](/src/path/to/file.ts#L88)
[`file.ts:88`](../../src/path/to/file.ts#L88)
```
> The `../../` prefix above is illustrative — compute the actual relative path from `{spec_file}`'s directory to each target file.
When there is only one concern, omit the bold label — just list the stops directly.
### Commit and Present
@ -53,7 +55,7 @@ When there is only one concern, omit the bold label — just list the stops dire
3. Open the spec in the user's editor so they can click through the Suggested Review Order:
- Run `code -r "{spec_file}"` to open the spec in the current VS Code window (reuses the window where the project or worktree is open). Always double-quote the path to handle spaces and special characters.
- If `code` is not available (command fails), skip gracefully and tell the user the spec file path instead.
4. Display summary of your work to the user, including the commit hash if one was created. Any file paths shown in conversation/terminal output must use CWD-relative format (no leading `/`) for terminal clickability — this differs from spec-file links which use project-root-relative paths. Include:
4. Display summary of your work to the user, including the commit hash if one was created. Any file paths shown in conversation/terminal output must use CWD-relative format (no leading `/`) with `:line` notation (e.g., `src/path/file.ts:42`) for terminal clickability — the goal is to make paths clickable in terminal emulators. Include:
- A note that the spec is open in their editor (or the file path if it couldn't be opened). Mention that `{spec_file}` now contains a Suggested Review Order.
- **Navigation tip:** "Ctrl+click (Cmd+click on macOS) the links in the Suggested Review Order to jump to each stop."
- Offer to push and/or create a pull request.

View File

@ -40,7 +40,7 @@ If version control is available and the tree is dirty, create a local commit wit
- If `code` is not available (command fails), skip gracefully and list the file paths instead.
2. Display a summary in conversation output, including:
- The commit hash (if one was created).
- List of files changed with one-line descriptions.
- List of files changed with one-line descriptions. Use CWD-relative paths (e.g., `src/path/file.ts`) for terminal clickability. No leading `/`.
- Review findings breakdown: patches applied, items deferred, items rejected. If all findings were rejected, say so.
3. Offer to push and/or create a pull request.