fix(checkpoint): address review findings from adversarial triage

Clarify review_mode state transition intent in generate-trail, label
step-02 walkthrough branches as normal vs fallback, replace circular
communication style rule with config variable refs, swap confirm gate
for [inferred] flag, and clarify stats data source as full diff.
This commit is contained in:
Alex Verkhovsky 2026-04-01 10:10:41 -07:00
parent c45cc35c60
commit 04d54d1734
4 changed files with 14 additions and 11 deletions

View File

@ -13,7 +13,7 @@ You are assisting the user in reviewing a change.
- **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.
- **Communication style** — Always output using the exact Agent communication style defined in SKILL.md and the loaded config.
- **Language** — Speak in `{communication_language}`. Write any file output in `{document_output_language}`.
## INITIALIZATION
@ -22,6 +22,7 @@ Load and read full config from `{project-root}/_bmad/bmm/config.yaml` and resolv
- `implementation_artifacts`
- `planning_artifacts`
- `communication_language`
- `document_output_language`
## FIRST STEP

View File

@ -33,6 +33,6 @@ I built a review trail for this {change_type} (no author-produced trail was foun
{generated trail}
```
Set review mode to `full-trail`. The generated trail is the Suggested Review Order for subsequent steps.
The generated trail serves as the Suggested Review Order for subsequent steps. Set `review_mode` to `full-trail` — a trail now exists, so all downstream steps should treat it as one.
If git is unavailable or the diff cannot be retrieved, return to step-01 with: "Could not generate trail — git unavailable."

View File

@ -51,7 +51,7 @@ Set `review_mode` — pick the first match:
1. **`full-trail`** — ENRICH found a spec with a `## Suggested Review Order` section. Intent source: spec's Intent section.
2. **`spec-only`** — ENRICH found a spec but it has no Suggested Review Order. Intent source: spec's Intent section.
3. **`bare-commit`** — no spec found. Intent source: commit message. If the commit message is terse (under 10 words), scan the diff for the primary change pattern and draft a one-sentence intent. Confirm with the user before proceeding.
3. **`bare-commit`** — no spec found. Intent source: commit message. If the commit message is terse (under 10 words), scan the diff for the primary change pattern and draft a one-sentence intent. Flag it as `[inferred]` in the output so the user can correct it.
## PRODUCE ORIENTATION
@ -63,24 +63,26 @@ Set `review_mode` — pick the first match:
### Surface Area Stats
Best-effort stats from `git diff --stat`. Try these baselines in order:
Best-effort stats derived from the diff. Try these baselines in order:
1. `baseline_commit` from the spec's frontmatter.
2. Branch merge-base against `main` (or the default branch).
3. `HEAD~1..HEAD` (latest commit only — tell the user).
4. If git is unavailable or all of the above fail, skip stats and note: "Could not compute stats."
Use `git diff --stat` and `git diff --numstat` for file-level counts, and scan the full diff content for the richer metrics.
Display as:
```
N files changed · M modules touched · ~L lines of logic · B boundary crossings · P new public interfaces
```
- **Files changed**: from `git diff --stat`.
- **Modules touched**: distinct top-level directories with changes.
- **Lines of logic**: added/modified lines excluding blanks, imports, formatting. `~` because approximate.
- **Files changed**: count from `git diff --stat`.
- **Modules touched**: distinct top-level directories with changes (from `--stat` file paths).
- **Lines of logic**: added/modified lines excluding blanks, imports, formatting. Scan diff content; `~` because approximate.
- **Boundary crossings**: changes spanning more than one top-level module. `0` if single module.
- **New public interfaces**: new exports, endpoints, public methods. `0` if none.
- **New public interfaces**: new exports, endpoints, public methods found in the diff. `0` if none.
Omit any metric you cannot compute rather than guessing.
@ -96,7 +98,7 @@ Omit any metric you cannot compute rather than guessing.
## FALLBACK TRAIL GENERATION
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.
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. If trail generation fails (e.g., git unavailable), the original review mode is preserved — step-02 handles this with its non-trail path.
## NEXT

View File

@ -11,14 +11,14 @@ Display: `Orientation → [Walkthrough] → Detail Pass → Testing`
### Identify Concerns
**With Suggested Review Order** (`full-trail` mode):
**With Suggested Review Order** (`full-trail` mode — the normal path, including when step-01 generated a trail):
1. Read the Suggested Review Order stops from the spec (or from conversation context if generated by step-01 fallback).
2. Resolve each stop to a file in the current repo. Output in `path:line` format per the standing rule.
3. Read the diff to understand what each stop actually does.
4. Group stops by concern. Stops that share a design intent belong together even if they're in different files. A stop may appear under multiple concerns if it serves multiple purposes.
**Without Suggested Review Order** (`spec-only` or `bare-commit` mode):
**Without Suggested Review Order** (fallback when trail generation failed, e.g., git unavailable):
1. Get the diff against the appropriate baseline (same rules as step 1).
2. Identify concerns by reading the diff for cohesive design intents: