refactor(checkpoint): extract fallback trail generation into generate-trail.md

Reduce step-01 bloat by moving the conditional trail generation
sub-routine into its own file, loaded only when review mode is
not full-trail.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Alex Verkhovsky 2026-04-01 08:09:26 -07:00
parent 26e415f2fd
commit 0d505257d3
2 changed files with 39 additions and 32 deletions

View File

@ -0,0 +1,38 @@
# Generate Review Trail
Generate a review trail from the diff and codebase context. A generated trail is lower quality than an author-produced one, but far better than none.
## Follow Global Step Rules in SKILL.md
## INSTRUCTIONS
1. Get the full diff against the appropriate baseline (same rules as Surface Area Stats in step-01).
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.
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.
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 using `path:line` per the global step rules:
```
**{Concern name}**
- {one-line framing, ≤15 words}
`src/path/to/file.ts:42`
```
When there is only one concern, omit the bold label — just list the stops directly.
## PRESENT
Output after the orientation:
```
I built a review trail for this {change_type} (no author-produced trail was found):
{generated trail}
```
Set review mode to `full-trail`. The generated trail is the Suggested Review Order for subsequent steps.
If git is unavailable or the diff cannot be retrieved, return to step-01 with: "Could not generate trail — git unavailable."

View File

@ -96,38 +96,7 @@ Omit any metric you cannot compute rather than guessing.
## FALLBACK TRAIL GENERATION ## FALLBACK TRAIL GENERATION
**Skip this section if review mode is `full-trail`.** If review mode is not `full-trail`, read fully and follow `./generate-trail.md` to build one from the diff. Then return here and continue to NEXT.
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).
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.
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.
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 using `path:line` per the global step rules:
```
**{Concern name}**
- {one-line framing, ≤15 words}
`src/path/to/file.ts:42`
```
When there is only one concern, omit the bold label — just list the stops directly.
Present after the orientation output:
```
I built a review trail for this {change_type} (no author-produced trail was found):
{generated trail}
```
Set review mode to `full-trail`. The generated trail is the Suggested Review Order for subsequent steps.
If git is unavailable or the diff cannot be retrieved, skip this section and proceed with the original review mode. Note: "Could not generate trail — git unavailable."
## NEXT ## NEXT