fix(checkpoint): align trail format with global step rules and add token budget

Use CWD-relative path:line in fallback trail (not markdown links),
cap full-file reads at ~50k tokens, remove over-prompted empty-tree SHA.

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
This commit is contained in:
Alex Verkhovsky 2026-04-01 07:16:35 -07:00
parent b6ae62ebf1
commit beeb2e1778
2 changed files with 5 additions and 5 deletions

View File

@ -11,7 +11,7 @@ You are assisting the user in reviewing a change.
## Global Step Rules (apply to every step) ## Global Step Rules (apply to every step)
- **Path:line format** — Every code reference must be clickable `path:line` (absolute or relative to repo root). - **Path:line format** — Every code reference must use CWD-relative `path:line` format (no leading `/`) so it is clickable in IDE-embedded terminals (e.g., `src/auth/middleware.ts:42`).
- **Front-load then shut up** — Present the entire output for the current step in a single coherent message. Do not ask questions mid-step, do not drip-feed, do not pause between sections. - **Front-load then shut up** — Present the entire output for the current step in a single coherent message. Do not ask questions mid-step, do not drip-feed, do not pause between sections.
- **Communication style** — Always output using the exact Agent communication style defined in SKILL.md and the loaded config. - **Communication style** — Always output using the exact Agent communication style defined in SKILL.md and the loaded config.

View File

@ -53,7 +53,7 @@ Set `change_type` based on how the user referred to the change:
Compute from `git diff --stat` against the appropriate baseline: Compute from `git diff --stat` against the appropriate baseline:
- **With spec**: Use `baseline_commit` from frontmatter. If missing, diff `HEAD~1..HEAD` and tell the user stats reflect only the latest commit. - **With spec**: Use `baseline_commit` from frontmatter. If missing, diff `HEAD~1..HEAD` and tell the user stats reflect only the latest commit.
- **Bare commit**: Diff against parent (`commit~1..commit`). For merge commits, use `--first-parent`. For initial commits, diff against the empty tree (`4b825dc..commit`). - **Bare commit**: Diff against parent (`commit~1..commit`). For merge commits, use `--first-parent`.
Display as: Display as:
@ -86,18 +86,18 @@ If git is unavailable or a command fails, show what you can and note what's miss
When no Suggested Review Order exists, generate one from the diff and codebase context. A generated trail is lower quality than an author-produced one, but far better than none. When no Suggested Review Order exists, generate one from the diff and codebase context. A generated trail is lower quality than an author-produced one, but far better than none.
1. Get the full diff against the appropriate baseline (same rules as Surface Area Stats). 1. Get the full diff against the appropriate baseline (same rules as Surface Area Stats).
2. Read changed files in full — not just diff hunks. Surrounding code reveals intent that hunks alone miss. 2. Read changed files in full — not just diff hunks. Surrounding code reveals intent that hunks alone miss. If total file content exceeds ~50k tokens, read only the files with the largest diff hunks in full and use hunks for the rest.
3. If a spec exists, use its Intent section to anchor concern identification. 3. If a spec exists, use its Intent section to anchor concern identification.
4. Identify 25 concerns: cohesive design intents that each explain *why* behind a cluster of changes. Prefer functional groupings and architectural boundaries over file-level splits. A single-concern change is fine — don't invent groupings. 4. Identify 25 concerns: cohesive design intents that each explain *why* behind a cluster of changes. Prefer functional groupings and architectural boundaries over file-level splits. A single-concern change is fine — don't invent groupings.
5. For each concern, select 14 `path:line` stops — locations where the concern is most visible. Prefer entry points, decision points, and boundary crossings over mechanical changes. 5. For each concern, select 14 `path:line` stops — locations where the concern is most visible. Prefer entry points, decision points, and boundary crossings over mechanical changes.
6. Lead with the entry point — the highest-leverage stop a reviewer should see first. Inside each concern, order stops so each builds on the previous. End with peripherals (tests, config, types). 6. Lead with the entry point — the highest-leverage stop a reviewer should see first. Inside each concern, order stops so each builds on the previous. End with peripherals (tests, config, types).
7. Format each stop as a workspace-relative markdown link — basename and line as link text, path with `#L` anchor as target: 7. Format each stop using `path:line` per the global step rules:
``` ```
**{Concern name}** **{Concern name}**
- {one-line framing, ≤15 words} - {one-line framing, ≤15 words}
[`file.ts:42`](/src/path/to/file.ts#L42) `src/path/to/file.ts:42`
``` ```
When there is only one concern, omit the bold label — just list the stops directly. When there is only one concern, omit the bold label — just list the stops directly.