|
|
|
|
@ -10,8 +10,57 @@
|
|
|
|
|
|
|
|
|
|
## INSTRUCTIONS
|
|
|
|
|
|
|
|
|
|
1. Change `{spec_file}` status to `done` in the frontmatter.
|
|
|
|
|
2. If version control is available and the tree is dirty, create a local commit with a conventional message derived from the spec title.
|
|
|
|
|
3. Display summary of your work to the user, including the commit hash if one was created. Advise on how to review the changes. Offer to push and/or create a pull request.
|
|
|
|
|
### Generate Suggested Review Order
|
|
|
|
|
|
|
|
|
|
Determine what changed:
|
|
|
|
|
|
|
|
|
|
- **Plan-code-review:** Read `{baseline_commit}` from `{spec_file}` frontmatter and construct the diff of all changes since that commit.
|
|
|
|
|
- **One-shot:** No baseline exists. Use the files you created or modified during implementation.
|
|
|
|
|
|
|
|
|
|
**Plan-code-review:** Append the review order as a `## Suggested Review Order` section to `{spec_file}` **after the last existing section**. Do not modify the Code Map.
|
|
|
|
|
|
|
|
|
|
**One-shot:** Display the review order directly in conversation output.
|
|
|
|
|
|
|
|
|
|
Build the trail as an ordered sequence of **stops** — clickable `path:line` references with brief framing — optimized for a human reviewer reading top-down to understand the change:
|
|
|
|
|
|
|
|
|
|
1. **Order by concern, not by file.** Group stops by the conceptual concern they address (e.g., "validation logic", "schema change", "UI binding"). A single file may appear under multiple concerns.
|
|
|
|
|
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.** 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.
|
|
|
|
|
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:
|
|
|
|
|
|
|
|
|
|
```markdown
|
|
|
|
|
## Suggested Review Order
|
|
|
|
|
|
|
|
|
|
**{Concern name}**
|
|
|
|
|
|
|
|
|
|
- {one-line framing}
|
|
|
|
|
[`file.ts:42`](/src/path/to/file.ts#L42)
|
|
|
|
|
|
|
|
|
|
- {one-line framing}
|
|
|
|
|
[`other.ts:17`](/src/path/to/other.ts#L17)
|
|
|
|
|
|
|
|
|
|
**{Next concern}**
|
|
|
|
|
|
|
|
|
|
- {one-line framing}
|
|
|
|
|
[`file.ts:88`](/src/path/to/file.ts#L88)
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
When there is only one concern, omit the bold label — just list the stops directly.
|
|
|
|
|
|
|
|
|
|
### Commit and Present
|
|
|
|
|
|
|
|
|
|
1. **Plan-code-review:** Change `{spec_file}` status to `done` in the frontmatter.
|
|
|
|
|
2. If version control is available and the tree is dirty, create a local commit with a conventional message derived from the spec title (plan-code-review) or the intent (one-shot).
|
|
|
|
|
3. **Plan-code-review only:** 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. Include:
|
|
|
|
|
- **Plan-code-review:** 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.
|
|
|
|
|
|
|
|
|
|
Workflow complete.
|
|
|
|
|
|
Jonah Schulte
Alex Verkhovsky