mirror of
https://github.com/garrytan/gstack.git
synced 2026-09-27 15:11:47 +02:00
v1.89.1.0 fix: remove continuous checkpoint commits (#2970)
* v1.89.1.0 fix: remove continuous checkpoint commits and repair validation blockers * fix: clarify shipping and engineering review recovery * fix: interpret native no-change review descriptions * test: separate descendant readiness from timeout delivery
This commit is contained in:
Garry Tan
+26
-32
@@ -337,31 +337,6 @@ For high-stakes ambiguity (architecture, data model, destructive scope, missing
|
||||
|
||||
A claimed limitation or requirement ("the API can't do this", "X requires a credential", "that's impossible on this platform") is a material claim. State one only with the verbatim error, the documented statement, or a live probe in hand — pattern-matching a failure to a familiar story is not evidence. When a cheap probe settles the question, run it BEFORE asking the user anything or declaring a step blocked.
|
||||
|
||||
## Continuous Checkpoint Mode
|
||||
|
||||
If `CHECKPOINT_MODE` is `"continuous"`: auto-commit completed logical units with `WIP:` prefix.
|
||||
|
||||
Commit after new intentional files, completed functions/modules, verified bug fixes, and before long-running install/build/test commands.
|
||||
|
||||
Commit format:
|
||||
|
||||
```
|
||||
WIP: <concise description of what changed>
|
||||
|
||||
[gstack-context]
|
||||
Decisions: <key choices made this step>
|
||||
Remaining: <what's left in the logical unit>
|
||||
Tried: <failed approaches worth recording> (omit if none)
|
||||
Skill: </skill-name-if-running>
|
||||
[/gstack-context]
|
||||
```
|
||||
|
||||
Rules: stage only intentional files, NEVER `git add -A`, do not commit broken tests or mid-edit state, and push only if `CHECKPOINT_PUSH` is `"true"`. Do not announce each WIP commit.
|
||||
|
||||
`/context-restore` reads `[gstack-context]`; `/ship` squashes WIP commits into clean commits.
|
||||
|
||||
If `CHECKPOINT_MODE` is `"explicit"`: ignore this section unless a skill or user asks to commit.
|
||||
|
||||
## Context Health (soft directive)
|
||||
|
||||
During long-running skill sessions, periodically write a brief `[PROGRESS]` summary: done, next, surprises.
|
||||
@@ -476,7 +451,9 @@ Skills that run plan reviews (`/plan-*-review`, `/codex review`) include the EXI
|
||||
|
||||
|
||||
## Priority hierarchy
|
||||
On compression: Step 0 > Test diagram > Opinionated recommendations > Everything else. Never skip Step 0 or the test diagram. The system handles context limits; do not preemptively warn.
|
||||
Complete every required stage, decision gate and output. Shorten only optional
|
||||
commentary, never Scope Challenge, Sections 1–4, the test diagram or required
|
||||
decision/report content. The system handles context limits; do not preemptively warn.
|
||||
|
||||
## My engineering preferences (use these to guide your recommendations):
|
||||
* **Shared code:** require common behavior and improved reliability or net savings; similar-looking code alone is insufficient.
|
||||
@@ -674,16 +651,33 @@ Scope Challenge is mandatory before Section 1.
|
||||
> **STOP.** Before starting the Scope Challenge and full review (after target selection and startup), Read `~/.claude/skills/gstack/plan-eng-review/sections/review-sections.md` and execute it
|
||||
> in full. Do not work from memory — that section is the source of truth for this step.
|
||||
|
||||
## Recovery routing
|
||||
|
||||
Use this routing at every STOP or failed verification; do not restart the review.
|
||||
|
||||
**Paused question:** Wait for its actual answer without completion telemetry or ExitPlanMode.
|
||||
Resume that question's local procedure with the answer. A missing-result call
|
||||
that may have surfaced is still pending; do not duplicate it.
|
||||
|
||||
**Repairable write/read failure:** Stop before the dependent question or output.
|
||||
Use that step's stated recovery, then repeat its full Read-back verification.
|
||||
If no recovery is specified or it fails, follow **Blocked outcome**. Never turn
|
||||
a failed permitted save into a chat-only success.
|
||||
|
||||
**Late change or missing work:** Return to the affected review stage; new or
|
||||
reopened choices use Decision procedure. Repeat Approval readiness, then Required
|
||||
outputs steps 1–4 for changed outputs before choosing navigation again. Refresh
|
||||
affected tests, tasks, dependencies and parallelization. Unchanged saved outputs
|
||||
may reuse their successful Review Log. If a final gate discovers stale evidence,
|
||||
follow **Blocked outcome** first; resume on this repair path.
|
||||
|
||||
**Blocked outcome:** Stop the review and report `BLOCKED`, the missing path/work, actual attempts and what is needed to resume. Label complete chat-only output **not persisted**; it supplies no saved-review or completion credit. If startup values and a permitted telemetry command are available, run **Telemetry (run last)** once with `OUTCOME=error` and the actual `ERROR_MESSAGE`/`FAILED_STEP`. Do not call ExitPlanMode. Resume at the failed step using Recovery routing.
|
||||
|
||||
## Section self-check (before you finish)
|
||||
|
||||
Confirm you read the section and completed Scope Challenge, Sections 1–4,
|
||||
Outside Voice and outputs. If evidence is missing, Read `sections/review-sections.md`
|
||||
and repair only gaps through its decision/output recovery steps. Preserve
|
||||
verified work.
|
||||
|
||||
**Paused question:** Wait for its actual answer without completion telemetry or ExitPlanMode.
|
||||
|
||||
**Blocked outcome:** Stop the review and report `BLOCKED`, the missing path/work, actual attempts and what is needed to resume. Label complete chat-only output **not persisted**; it supplies no saved-review or completion credit. If startup values and a permitted telemetry command are available, run **Telemetry (run last)** once with `OUTCOME=error` and the actual `ERROR_MESSAGE`/`FAILED_STEP`. Do not call ExitPlanMode. Resume at the failed step and repeat affected outputs, read-back and logs.
|
||||
and use Recovery routing above. Preserve verified work.
|
||||
|
||||
## EXIT PLAN MODE GATE (BLOCKING)
|
||||
|
||||
|
||||
@@ -80,7 +80,9 @@ Keep the reviewed target fixed when selecting the section's separate report dest
|
||||
{{GBRAIN_CONTEXT_LOAD}}
|
||||
|
||||
## Priority hierarchy
|
||||
On compression: Step 0 > Test diagram > Opinionated recommendations > Everything else. Never skip Step 0 or the test diagram. The system handles context limits; do not preemptively warn.
|
||||
Complete every required stage, decision gate and output. Shorten only optional
|
||||
commentary, never Scope Challenge, Sections 1–4, the test diagram or required
|
||||
decision/report content. The system handles context limits; do not preemptively warn.
|
||||
|
||||
## My engineering preferences (use these to guide your recommendations):
|
||||
* **Shared code:** require common behavior and improved reliability or net savings; similar-looking code alone is insufficient.
|
||||
@@ -153,16 +155,33 @@ Scope Challenge is mandatory before Section 1.
|
||||
|
||||
{{SECTION:review-sections}}
|
||||
|
||||
## Recovery routing
|
||||
|
||||
Use this routing at every STOP or failed verification; do not restart the review.
|
||||
|
||||
**Paused question:** Wait for its actual answer without completion telemetry or ExitPlanMode.
|
||||
Resume that question's local procedure with the answer. A missing-result call
|
||||
that may have surfaced is still pending; do not duplicate it.
|
||||
|
||||
**Repairable write/read failure:** Stop before the dependent question or output.
|
||||
Use that step's stated recovery, then repeat its full Read-back verification.
|
||||
If no recovery is specified or it fails, follow **Blocked outcome**. Never turn
|
||||
a failed permitted save into a chat-only success.
|
||||
|
||||
**Late change or missing work:** Return to the affected review stage; new or
|
||||
reopened choices use Decision procedure. Repeat Approval readiness, then Required
|
||||
outputs steps 1–4 for changed outputs before choosing navigation again. Refresh
|
||||
affected tests, tasks, dependencies and parallelization. Unchanged saved outputs
|
||||
may reuse their successful Review Log. If a final gate discovers stale evidence,
|
||||
follow **Blocked outcome** first; resume on this repair path.
|
||||
|
||||
**Blocked outcome:** Stop the review and report `BLOCKED`, the missing path/work, actual attempts and what is needed to resume. Label complete chat-only output **not persisted**; it supplies no saved-review or completion credit. If startup values and a permitted telemetry command are available, run **Telemetry (run last)** once with `OUTCOME=error` and the actual `ERROR_MESSAGE`/`FAILED_STEP`. Do not call ExitPlanMode. Resume at the failed step using Recovery routing.
|
||||
|
||||
## Section self-check (before you finish)
|
||||
|
||||
Confirm you read the section and completed Scope Challenge, Sections 1–4,
|
||||
Outside Voice and outputs. If evidence is missing, Read `sections/review-sections.md`
|
||||
and repair only gaps through its decision/output recovery steps. Preserve
|
||||
verified work.
|
||||
|
||||
**Paused question:** Wait for its actual answer without completion telemetry or ExitPlanMode.
|
||||
|
||||
**Blocked outcome:** Stop the review and report `BLOCKED`, the missing path/work, actual attempts and what is needed to resume. Label complete chat-only output **not persisted**; it supplies no saved-review or completion credit. If startup values and a permitted telemetry command are available, run **Telemetry (run last)** once with `OUTCOME=error` and the actual `ERROR_MESSAGE`/`FAILED_STEP`. Do not call ExitPlanMode. Resume at the failed step and repeat affected outputs, read-back and logs.
|
||||
and use Recovery routing above. Preserve verified work.
|
||||
|
||||
{{EXIT_PLAN_MODE_GATE}}
|
||||
|
||||
|
||||
@@ -2,9 +2,13 @@
|
||||
<!-- Regenerate: bun run gen:skill-docs -->
|
||||
## Review preparation
|
||||
|
||||
After startup, follow the preparation sections below through Confidence
|
||||
Calibration. Read Decision procedure as the rule for later choices. Start the
|
||||
review at Scope Challenge, then complete Sections 1–4 in order.
|
||||
After startup, prepare in this order:
|
||||
1. Select the report file and permissions under **Review record and write policy**.
|
||||
2. Run **Prior Learnings** and resolve its configuration question.
|
||||
3. Run **Retrospective learning** on existing target paths.
|
||||
4. Read **Confidence Calibration** and **Decision procedure** as rules, not review passes.
|
||||
|
||||
Then run **Scope Challenge A → B → C**, followed by Sections 1–4 in order.
|
||||
|
||||
## Review record and write policy
|
||||
|
||||
@@ -51,11 +55,11 @@ The QA Test Plan and task JSONL intentionally use legacy discovery paths under
|
||||
and `tasks-eng-review-{datetime}.jsonl`. QA and /autoplan require these paths even
|
||||
with a different report root. Use their formats/commands below; do not relocate them.
|
||||
|
||||
A failed permitted save is different from forbidden writing. Use the failed
|
||||
step's stated recovery; if saving or read-back still fails, take **Blocked
|
||||
outcome**. Do not ask from an unsaved record or convert a failed save into the
|
||||
chat-only route. Forbidden auxiliary writes allow the review to continue;
|
||||
unrecovered attempted writes block it. Apply this policy at every later write.
|
||||
A failed permitted save uses **Recovery routing → Repairable write/read failure**,
|
||||
not the forbidden-write branches above. Do not ask from an unsaved record.
|
||||
Forbidden auxiliary writes allow the review to continue; unrecovered attempted
|
||||
writes block it. Best-effort logs retain their stated non-blocking behavior.
|
||||
Apply this policy at every later write.
|
||||
|
||||
## Prior Learnings
|
||||
|
||||
@@ -184,9 +188,8 @@ Voice, late changes and TODO choices. Finish one choice before the next.
|
||||
|
||||
Setup gates—Context Recovery/prerequisites, Prior Learnings configuration,
|
||||
target and Scope Challenge complexity selectors—use local rules without a
|
||||
pre-answer ledger. These answers approve no engineering remedy.
|
||||
|
||||
Flow: issue -> compare -> save/read -> ask/wait -> apply -> next issue.
|
||||
pre-answer ledger. Scope Challenge B saves actual selector answers afterward;
|
||||
it does not use this remedy loop. These answers approve no engineering remedy.
|
||||
|
||||
One question for one choice per AskUserQuestion call. Use the preamble for
|
||||
question transport/fallback and authorized auto-decisions. Use Review
|
||||
@@ -248,9 +251,7 @@ extra CC effort is marginal. Fit headers and labels to host limits now, before
|
||||
saving. Without stated limits, keep both under 5 words; details go in descriptions.
|
||||
|
||||
For one fixed approved contract, coverage choices vary implementation or proof
|
||||
depth. Use `Completeness: N/10`: 10 covers all relevant in-scope edges, 7 covers
|
||||
the happy path, 3 is a shortcut. For different approaches, use
|
||||
`Note: options differ in kind, not coverage — no completeness score.`
|
||||
depth. Apply the preamble's Completeness scores or kind-note accordingly.
|
||||
Test-review scores rate existing/proposed tests, not answer status.
|
||||
|
||||
**Audit the commitments.** Build a separate **comparison grid** for the whole
|
||||
@@ -287,9 +288,6 @@ After the jitter answer, carry that value into both options of the later cap que
|
||||
|
||||
### 4. Save the pending record
|
||||
|
||||
Invariant for this step: save one complete current record, Read that record
|
||||
back, then ask the exact saved question. Do not ask from memory.
|
||||
|
||||
Save the record, complete grid and exact `currentDecision` in the report file,
|
||||
before `## GSTACK REVIEW REPORT`. Include every native field, the recommendation
|
||||
and all options. A–D record selectors are ledger notation only: if a saved label
|
||||
@@ -329,8 +327,7 @@ Compare every native field with `currentDecision` and the whole grid with step 3
|
||||
Read after the final edit, even if Edit says the content is current in context.
|
||||
Grep, chat references, summaries and planned writes do not verify the record.
|
||||
Repair any difference and repeat the complete Read before asking. A failed save
|
||||
blocks the question; an unreadable or unverifiable record follows the write
|
||||
policy's recovery and then **Blocked outcome** if still unresolved.
|
||||
blocks the question; unreadable or unverifiable records use **Recovery routing**.
|
||||
|
||||
On the permitted read-only route, present the complete record and grid as **not
|
||||
persisted** and compare them with `currentDecision`. This can support the chat
|
||||
@@ -359,9 +356,6 @@ answer. An obvious fix still needs an answer unless exact prior approval covers
|
||||
|
||||
### 6. Apply and refresh
|
||||
|
||||
Invariant for this step: apply the selected option as one complete resolution
|
||||
block, Read it back, then continue. Do not update only the answer line.
|
||||
|
||||
Read the selected saved label, full description and grid column together. Carry
|
||||
all commitments, conditions, unchanged values and pending choices forward. If
|
||||
they conflict or bundle independent choices, preserve the actual answer, explain
|
||||
@@ -394,11 +388,15 @@ audit trail, leaving User Challenges for its final gate.
|
||||
|
||||
## Scope Challenge
|
||||
|
||||
Before reviewing, answer:
|
||||
1. **What already solves each sub-problem?** Inspect helpers, libraries, callers and reusable outputs: behavior and dependency/deployment boundaries. Cite authored sources; label proposed callers with their motivating plan requirement and assumptions.
|
||||
2. **What minimum changes achieve the goal?** Flag work deferrable without blocking it; challenge scope creep.
|
||||
3. **Complexity check:** Count files and new classes/services; seek fewer moving parts. Apply the gate below.
|
||||
4. **Search check:** For each new architectural pattern, infrastructure component
|
||||
### A. Assess the target
|
||||
|
||||
Complete these checks before the complexity decision in B. Do not apply scope
|
||||
changes or write findings into the plan yet.
|
||||
|
||||
- **What already solves each sub-problem?** Inspect helpers, libraries, callers and reusable outputs: behavior and dependency/deployment boundaries. Cite authored sources; label proposed callers with their motivating plan requirement and assumptions.
|
||||
- **What minimum changes achieve the goal?** Flag work deferrable without blocking it; challenge scope creep.
|
||||
- **Complexity check:** Count files and new classes/services; seek fewer moving parts. Use these counts in B.
|
||||
- **Search check:** For each new architectural pattern, infrastructure component
|
||||
or concurrency approach, research built-ins, current practice and pitfalls
|
||||
through Aside (entrypoint readiness), one read-only request per pattern:
|
||||
|
||||
@@ -413,17 +411,20 @@ Before reviewing, answer:
|
||||
Prefer available built-ins. Label recommendations **[Layer 1]**, **[Layer 2]**,
|
||||
**[Layer 3]** or **[EUREKA]** per Search Before Building; explain departures
|
||||
from standard practice.
|
||||
5. **TODOS cross-reference:** Read existing `TODOS.md`: what blocks this plan,
|
||||
- **TODOS cross-reference:** Read existing `TODOS.md`: what blocks this plan,
|
||||
fits this PR without expanding scope, or needs a new TODO?
|
||||
|
||||
6. **Completeness check:** Full tests, edges and errors cost 10-100x less with AI.
|
||||
- **Completeness check:** Full tests, edges and errors cost 10-100x less with AI.
|
||||
Prefer completeness when a shortcut saves only CC+gstack minutes. Boil the ocean.
|
||||
|
||||
7. **Distribution check:** For new artifacts, verify build/publish CI/CD, target
|
||||
- **Distribution check:** For new artifacts, verify build/publish CI/CD, target
|
||||
OS/architectures and download/install channels. Put deferrals in "NOT in scope".
|
||||
|
||||
### B. Resolve complexity selectors
|
||||
|
||||
Below both thresholds, skip B's questions and go directly to **C. Resolve findings**.
|
||||
At 8+ files or 2+ new classes/services, STOP before Section 1. Use the
|
||||
preamble's decision-brief format for this complexity gate.
|
||||
preamble's decision-brief format for this complexity gate, in this order:
|
||||
|
||||
Initial scope selectors need no grid or **pre-answer** ledger write. Ask and
|
||||
wait before changes.
|
||||
@@ -439,14 +440,23 @@ wait before changes.
|
||||
question; unapproved fixes stay pending. If no smaller arrangement preserves
|
||||
these commitments, explain that and offer confirmation of the original
|
||||
arrangement or a pause to investigate a smaller one. Wait for the answer.
|
||||
A pause leaves the arrangement undecided: investigate only the agreed question,
|
||||
then return to this structure selector. Do not continue to C until it is settled.
|
||||
3. Save the actual feature and structure answers as one scope record: `feature
|
||||
answers: <refs>; structure: <A/B + ref>; accepted scope: <exact scope>;
|
||||
pending remedies: <ids or none>`.
|
||||
|
||||
Save this record under the write policy; no retroactive pending record.
|
||||
This is a post-answer scope summary, not a remedy's pending ledger record.
|
||||
Save it under the write policy and Read it back against the actual answers;
|
||||
on the permitted read-only route, present and verify it as **not persisted**.
|
||||
Do not invent a pre-answer record afterward. A failed save or Read blocks advancement.
|
||||
|
||||
After any complexity answers, apply only accepted scope changes. Do not re-argue
|
||||
reduction or skip approved components. Below the threshold, start at step 1.
|
||||
After verification, apply only accepted scope changes. Do not re-argue reduction
|
||||
or skip approved components. Continue to **C. Resolve findings**.
|
||||
|
||||
### C. Resolve findings
|
||||
|
||||
Run C whether B was completed or skipped.
|
||||
|
||||
1. Present numbered Scope Challenge findings with calibrated severity, confidence
|
||||
and source; use "No issues found" for an empty list.
|
||||
@@ -514,14 +524,9 @@ Use Decision procedure for new/reopened extraction choices; scope approval does
|
||||
|
||||
### 3. Test review
|
||||
|
||||
For a plan target, review proposed coverage against proposed paths. For a
|
||||
branch-diff target, diagram changed code paths plus callers/tests; the working
|
||||
plan is the remedy plan from diff findings.
|
||||
|
||||
For shared-code changes, audit existing/missing shared-contract tests (behavior,
|
||||
errors, side effects, boundaries) and each migrated caller's integration/differences.
|
||||
Reuse meaningful tests; account for their costs and shared failure risk per rubric. Rejected
|
||||
extractions still need coverage for real duplicated-code defects.
|
||||
Rejected extractions still need coverage for real duplicated-code defects.
|
||||
|
||||
100% coverage is the goal. Identify the tests each planned codepath needs. Add required proof for an exact approved behavior without asking again; take new policies or optional verification depth through the decision gate before treating their tests as accepted work. Review the requirements here; do not build the proposed tests.
|
||||
|
||||
@@ -571,8 +576,8 @@ Read the plan document. For each new feature, service, endpoint, or component de
|
||||
- What transforms it? (validation, mapping, computation)
|
||||
- Where does it go? (database write, API response, rendered output, side effect)
|
||||
- What can go wrong at each step? (null/undefined, invalid input, network failure, empty collection)
|
||||
3. **Diagram the execution.** For each changed file, draw an ASCII diagram showing:
|
||||
- Every function/method that was added or modified
|
||||
3. **Diagram the execution.** For each existing or proposed component in the selected target, draw an ASCII diagram showing:
|
||||
- Every existing or proposed function/method in scope
|
||||
- Every conditional branch (if/else, switch, ternary, guard clause, early return)
|
||||
- Every error path (try/catch, rescue, error boundary, fallback)
|
||||
- Every call to another function (trace into it — does IT have untested branches?)
|
||||
@@ -582,7 +587,7 @@ This is the critical step — you're building a map of every line of code that c
|
||||
|
||||
**Step 2. Map user flows, interactions, and error states:**
|
||||
|
||||
Code coverage isn't enough — you need to cover how real users interact with the changed code. For each changed feature, think through:
|
||||
Code coverage isn't enough — you need to cover how real users interact with the selected target. For each existing or proposed feature, think through:
|
||||
|
||||
- **User flows:** What sequence of actions does a user take that touches this code? Map the full journey (e.g., "user clicks 'Pay' → form validates → API call → success/failure screen"). Each step in the journey needs a test.
|
||||
- **Interaction edge cases:** What happens when the user does something unexpected?
|
||||
@@ -727,7 +732,7 @@ Repo: {owner/repo}
|
||||
|
||||
This file is consumed by `/qa` and `/qa-only` as primary test input. Include only the information that helps a QA tester know **what to test and where** — not implementation details.
|
||||
|
||||
After the Test Plan Artifact is saved or presented, report the Test review findings and their dispositions and continue to Performance review. The Test review's **Add missing tests to the plan** step resolves test and eval decisions before that artifact is written.
|
||||
After the Test Plan Artifact is saved or presented, report the Test review findings and their dispositions and continue to Performance review.
|
||||
|
||||
### 4. Performance review
|
||||
Evaluate:
|
||||
@@ -988,11 +993,12 @@ Retain the historical review-log skill ID; add `"host":"claude","outside_provide
|
||||
|
||||
### Continue after Outside Voice
|
||||
|
||||
Complete the chosen Outside Voice branch, including its accurate coverage record. Only completed reviews enter Cross-model tension. Continue to Final planning decisions and the approval check before Required outputs; report disabled or unavailable coverage in the Completion summary.
|
||||
Only completed reviews enter Cross-model tension. Record the actual coverage,
|
||||
including disabled or unavailable outcomes, then continue below.
|
||||
|
||||
## Final planning decisions
|
||||
|
||||
After Sections 1–4 and the Outside Voice path, resolve the TODO choices below. Then run the approval check before preparing final outputs.
|
||||
Resolve the TODO choices, then check Approval readiness before Required outputs.
|
||||
|
||||
### TODOS.md updates
|
||||
Review every potential TODO. Reuse an exact prior disposition under Decision procedure; ask about each unanswered proposal in its own AskUserQuestion. Never batch TODOs or silently skip them. Use `~/.claude/skills/gstack/review/TODOS-format.md`.
|
||||
@@ -1022,12 +1028,10 @@ unresolved decisions in the report.
|
||||
|
||||
## Required outputs
|
||||
|
||||
Run this finish sequence after Approval readiness passes. The reference sections
|
||||
below supply content, formats and commands for the named step; they do not start
|
||||
another review cycle.
|
||||
Run this finish sequence after Approval readiness passes. Use the references
|
||||
below for each step, not as another review cycle.
|
||||
|
||||
On recovery, resume at the failed step. Reuse a successful Review Log for
|
||||
unchanged saved outputs; changed outputs must pass steps 1–4 again.
|
||||
For recovery or changed outputs, use the entrypoint's **Recovery routing**.
|
||||
|
||||
1. **Prepare the review body.** Use the output reference below to complete the
|
||||
working plan, Implementation Tasks and Completion summary. Derive unresolved
|
||||
@@ -1044,19 +1048,15 @@ unchanged saved outputs; changed outputs must pass steps 1–4 again.
|
||||
4. **Publish.** Display the Review Readiness Dashboard, then present the saved
|
||||
Completion summary to the user.
|
||||
5. **Choose navigation.** Use Next Steps — Review Chaining and wait for its answer.
|
||||
Navigation grants no implementation authority. If a substantive change arises,
|
||||
resolve it through Decision procedure, repeat Approval readiness, and redo the
|
||||
affected outputs from step 1 through publication before asking navigation again.
|
||||
Navigation grants no implementation authority. A substantive change follows
|
||||
**Recovery routing → Late change or missing work** before navigation resumes.
|
||||
6. **Finish.** Run Learning hooks, then return to the entrypoint's Section
|
||||
self-check and read-only EXIT PLAN MODE GATE. Run these checks in every host
|
||||
mode. Brain Calibration Write-Back is one gated Learning hook. Only after
|
||||
both pass, run success telemetry and cache refresh; call ExitPlanMode only in
|
||||
host plan mode.
|
||||
mode; its final instructions govern telemetry, cache refresh and exit.
|
||||
|
||||
### Output reference — review body
|
||||
|
||||
Keep the working plan, findings, ledger and the sections below together in the
|
||||
report file. Place `Suppressed findings` as a body appendix before the terminal
|
||||
Place `Suppressed findings` as a body appendix before the terminal
|
||||
`## GSTACK REVIEW REPORT`; nothing follows that terminal report.
|
||||
|
||||
### "NOT in scope" section
|
||||
@@ -1382,9 +1382,6 @@ without adding or strengthening them in the question or descriptions. A test
|
||||
required before editing one function does not make every independent lane wait.
|
||||
A next-step answer approves no implementation change.
|
||||
|
||||
For a substantive late change, follow the repeat path in finish step 5. Refresh
|
||||
affected tasks, dependencies and parallelization along with the other outputs.
|
||||
|
||||
## Learning hooks
|
||||
|
||||
In finish step 6, keep the working plan/approvals fixed. Review operational learnings
|
||||
@@ -1419,6 +1416,8 @@ already knows. A good test: would this insight save time in a future session? If
|
||||
|
||||
## Brain Calibration Write-Back (gated)
|
||||
|
||||
`BRAIN_CALIBRATION_WRITEBACK` is a reserved default-off gate; this runtime does not set it. Skip this section and continue the finish sequence. Do not enable it or infer permission from brain availability. The contract below is retained for future gated integration, not an instruction to write now.
|
||||
|
||||
Skip unless `BRAIN_CALIBRATION_WRITEBACK` is set and the preamble/brain-health
|
||||
output or gstack config shows `brain_trust_policy@<endpoint-hash>=personal`.
|
||||
If unknown, skip. If both gates pass, record one durable
|
||||
|
||||
@@ -1,8 +1,12 @@
|
||||
## Review preparation
|
||||
|
||||
After startup, follow the preparation sections below through Confidence
|
||||
Calibration. Read Decision procedure as the rule for later choices. Start the
|
||||
review at Scope Challenge, then complete Sections 1–4 in order.
|
||||
After startup, prepare in this order:
|
||||
1. Select the report file and permissions under **Review record and write policy**.
|
||||
2. Run **Prior Learnings** and resolve its configuration question.
|
||||
3. Run **Retrospective learning** on existing target paths.
|
||||
4. Read **Confidence Calibration** and **Decision procedure** as rules, not review passes.
|
||||
|
||||
Then run **Scope Challenge A → B → C**, followed by Sections 1–4 in order.
|
||||
|
||||
## Review record and write policy
|
||||
|
||||
@@ -49,11 +53,11 @@ The QA Test Plan and task JSONL intentionally use legacy discovery paths under
|
||||
and `tasks-eng-review-{datetime}.jsonl`. QA and /autoplan require these paths even
|
||||
with a different report root. Use their formats/commands below; do not relocate them.
|
||||
|
||||
A failed permitted save is different from forbidden writing. Use the failed
|
||||
step's stated recovery; if saving or read-back still fails, take **Blocked
|
||||
outcome**. Do not ask from an unsaved record or convert a failed save into the
|
||||
chat-only route. Forbidden auxiliary writes allow the review to continue;
|
||||
unrecovered attempted writes block it. Apply this policy at every later write.
|
||||
A failed permitted save uses **Recovery routing → Repairable write/read failure**,
|
||||
not the forbidden-write branches above. Do not ask from an unsaved record.
|
||||
Forbidden auxiliary writes allow the review to continue; unrecovered attempted
|
||||
writes block it. Best-effort logs retain their stated non-blocking behavior.
|
||||
Apply this policy at every later write.
|
||||
|
||||
{{LEARNINGS_SEARCH}}
|
||||
|
||||
@@ -85,9 +89,8 @@ Voice, late changes and TODO choices. Finish one choice before the next.
|
||||
|
||||
Setup gates—Context Recovery/prerequisites, Prior Learnings configuration,
|
||||
target and Scope Challenge complexity selectors—use local rules without a
|
||||
pre-answer ledger. These answers approve no engineering remedy.
|
||||
|
||||
Flow: issue -> compare -> save/read -> ask/wait -> apply -> next issue.
|
||||
pre-answer ledger. Scope Challenge B saves actual selector answers afterward;
|
||||
it does not use this remedy loop. These answers approve no engineering remedy.
|
||||
|
||||
One question for one choice per AskUserQuestion call. Use the preamble for
|
||||
question transport/fallback and authorized auto-decisions. Use Review
|
||||
@@ -149,9 +152,7 @@ extra CC effort is marginal. Fit headers and labels to host limits now, before
|
||||
saving. Without stated limits, keep both under 5 words; details go in descriptions.
|
||||
|
||||
For one fixed approved contract, coverage choices vary implementation or proof
|
||||
depth. Use `Completeness: N/10`: 10 covers all relevant in-scope edges, 7 covers
|
||||
the happy path, 3 is a shortcut. For different approaches, use
|
||||
`Note: options differ in kind, not coverage — no completeness score.`
|
||||
depth. Apply the preamble's Completeness scores or kind-note accordingly.
|
||||
Test-review scores rate existing/proposed tests, not answer status.
|
||||
|
||||
**Audit the commitments.** Build a separate **comparison grid** for the whole
|
||||
@@ -188,9 +189,6 @@ After the jitter answer, carry that value into both options of the later cap que
|
||||
|
||||
### 4. Save the pending record
|
||||
|
||||
Invariant for this step: save one complete current record, Read that record
|
||||
back, then ask the exact saved question. Do not ask from memory.
|
||||
|
||||
Save the record, complete grid and exact `currentDecision` in the report file,
|
||||
before `## GSTACK REVIEW REPORT`. Include every native field, the recommendation
|
||||
and all options. A–D record selectors are ledger notation only: if a saved label
|
||||
@@ -230,8 +228,7 @@ Compare every native field with `currentDecision` and the whole grid with step 3
|
||||
Read after the final edit, even if Edit says the content is current in context.
|
||||
Grep, chat references, summaries and planned writes do not verify the record.
|
||||
Repair any difference and repeat the complete Read before asking. A failed save
|
||||
blocks the question; an unreadable or unverifiable record follows the write
|
||||
policy's recovery and then **Blocked outcome** if still unresolved.
|
||||
blocks the question; unreadable or unverifiable records use **Recovery routing**.
|
||||
|
||||
On the permitted read-only route, present the complete record and grid as **not
|
||||
persisted** and compare them with `currentDecision`. This can support the chat
|
||||
@@ -260,9 +257,6 @@ answer. An obvious fix still needs an answer unless exact prior approval covers
|
||||
|
||||
### 6. Apply and refresh
|
||||
|
||||
Invariant for this step: apply the selected option as one complete resolution
|
||||
block, Read it back, then continue. Do not update only the answer line.
|
||||
|
||||
Read the selected saved label, full description and grid column together. Carry
|
||||
all commitments, conditions, unchanged values and pending choices forward. If
|
||||
they conflict or bundle independent choices, preserve the actual answer, explain
|
||||
@@ -295,11 +289,15 @@ audit trail, leaving User Challenges for its final gate.
|
||||
|
||||
## Scope Challenge
|
||||
|
||||
Before reviewing, answer:
|
||||
1. **What already solves each sub-problem?** Inspect helpers, libraries, callers and reusable outputs: behavior and dependency/deployment boundaries. Cite authored sources; label proposed callers with their motivating plan requirement and assumptions.
|
||||
2. **What minimum changes achieve the goal?** Flag work deferrable without blocking it; challenge scope creep.
|
||||
3. **Complexity check:** Count files and new classes/services; seek fewer moving parts. Apply the gate below.
|
||||
4. **Search check:** For each new architectural pattern, infrastructure component
|
||||
### A. Assess the target
|
||||
|
||||
Complete these checks before the complexity decision in B. Do not apply scope
|
||||
changes or write findings into the plan yet.
|
||||
|
||||
- **What already solves each sub-problem?** Inspect helpers, libraries, callers and reusable outputs: behavior and dependency/deployment boundaries. Cite authored sources; label proposed callers with their motivating plan requirement and assumptions.
|
||||
- **What minimum changes achieve the goal?** Flag work deferrable without blocking it; challenge scope creep.
|
||||
- **Complexity check:** Count files and new classes/services; seek fewer moving parts. Use these counts in B.
|
||||
- **Search check:** For each new architectural pattern, infrastructure component
|
||||
or concurrency approach, research built-ins, current practice and pitfalls
|
||||
through Aside (entrypoint readiness), one read-only request per pattern:
|
||||
|
||||
@@ -314,17 +312,20 @@ Before reviewing, answer:
|
||||
Prefer available built-ins. Label recommendations **[Layer 1]**, **[Layer 2]**,
|
||||
**[Layer 3]** or **[EUREKA]** per Search Before Building; explain departures
|
||||
from standard practice.
|
||||
5. **TODOS cross-reference:** Read existing `TODOS.md`: what blocks this plan,
|
||||
- **TODOS cross-reference:** Read existing `TODOS.md`: what blocks this plan,
|
||||
fits this PR without expanding scope, or needs a new TODO?
|
||||
|
||||
6. **Completeness check:** Full tests, edges and errors cost 10-100x less with AI.
|
||||
- **Completeness check:** Full tests, edges and errors cost 10-100x less with AI.
|
||||
Prefer completeness when a shortcut saves only CC+gstack minutes. Boil the ocean.
|
||||
|
||||
7. **Distribution check:** For new artifacts, verify build/publish CI/CD, target
|
||||
- **Distribution check:** For new artifacts, verify build/publish CI/CD, target
|
||||
OS/architectures and download/install channels. Put deferrals in "NOT in scope".
|
||||
|
||||
### B. Resolve complexity selectors
|
||||
|
||||
Below both thresholds, skip B's questions and go directly to **C. Resolve findings**.
|
||||
At 8+ files or 2+ new classes/services, STOP before Section 1. Use the
|
||||
preamble's decision-brief format for this complexity gate.
|
||||
preamble's decision-brief format for this complexity gate, in this order:
|
||||
|
||||
Initial scope selectors need no grid or **pre-answer** ledger write. Ask and
|
||||
wait before changes.
|
||||
@@ -340,14 +341,23 @@ wait before changes.
|
||||
question; unapproved fixes stay pending. If no smaller arrangement preserves
|
||||
these commitments, explain that and offer confirmation of the original
|
||||
arrangement or a pause to investigate a smaller one. Wait for the answer.
|
||||
A pause leaves the arrangement undecided: investigate only the agreed question,
|
||||
then return to this structure selector. Do not continue to C until it is settled.
|
||||
3. Save the actual feature and structure answers as one scope record: `feature
|
||||
answers: <refs>; structure: <A/B + ref>; accepted scope: <exact scope>;
|
||||
pending remedies: <ids or none>`.
|
||||
|
||||
Save this record under the write policy; no retroactive pending record.
|
||||
This is a post-answer scope summary, not a remedy's pending ledger record.
|
||||
Save it under the write policy and Read it back against the actual answers;
|
||||
on the permitted read-only route, present and verify it as **not persisted**.
|
||||
Do not invent a pre-answer record afterward. A failed save or Read blocks advancement.
|
||||
|
||||
After any complexity answers, apply only accepted scope changes. Do not re-argue
|
||||
reduction or skip approved components. Below the threshold, start at step 1.
|
||||
After verification, apply only accepted scope changes. Do not re-argue reduction
|
||||
or skip approved components. Continue to **C. Resolve findings**.
|
||||
|
||||
### C. Resolve findings
|
||||
|
||||
Run C whether B was completed or skipped.
|
||||
|
||||
1. Present numbered Scope Challenge findings with calibrated severity, confidence
|
||||
and source; use "No issues found" for an empty list.
|
||||
@@ -388,18 +398,13 @@ Use Decision procedure for new/reopened extraction choices; scope approval does
|
||||
|
||||
### 3. Test review
|
||||
|
||||
For a plan target, review proposed coverage against proposed paths. For a
|
||||
branch-diff target, diagram changed code paths plus callers/tests; the working
|
||||
plan is the remedy plan from diff findings.
|
||||
|
||||
For shared-code changes, audit existing/missing shared-contract tests (behavior,
|
||||
errors, side effects, boundaries) and each migrated caller's integration/differences.
|
||||
Reuse meaningful tests; account for their costs and shared failure risk per rubric. Rejected
|
||||
extractions still need coverage for real duplicated-code defects.
|
||||
Rejected extractions still need coverage for real duplicated-code defects.
|
||||
|
||||
{{TEST_COVERAGE_AUDIT_PLAN}}
|
||||
|
||||
After the Test Plan Artifact is saved or presented, report the Test review findings and their dispositions and continue to Performance review. The Test review's **Add missing tests to the plan** step resolves test and eval decisions before that artifact is written.
|
||||
After the Test Plan Artifact is saved or presented, report the Test review findings and their dispositions and continue to Performance review.
|
||||
|
||||
### 4. Performance review
|
||||
Evaluate:
|
||||
@@ -409,11 +414,12 @@ Evaluate:
|
||||
|
||||
### Continue after Outside Voice
|
||||
|
||||
Complete the chosen Outside Voice branch, including its accurate coverage record. Only completed reviews enter Cross-model tension. Continue to Final planning decisions and the approval check before Required outputs; report disabled or unavailable coverage in the Completion summary.
|
||||
Only completed reviews enter Cross-model tension. Record the actual coverage,
|
||||
including disabled or unavailable outcomes, then continue below.
|
||||
|
||||
## Final planning decisions
|
||||
|
||||
After Sections 1–4 and the Outside Voice path, resolve the TODO choices below. Then run the approval check before preparing final outputs.
|
||||
Resolve the TODO choices, then check Approval readiness before Required outputs.
|
||||
|
||||
### TODOS.md updates
|
||||
Review every potential TODO. Reuse an exact prior disposition under Decision procedure; ask about each unanswered proposal in its own AskUserQuestion. Never batch TODOs or silently skip them. Use `~/.claude/skills/gstack/review/TODOS-format.md`.
|
||||
@@ -430,12 +436,10 @@ Option C records accepted implementation scope; still do not edit product code.
|
||||
|
||||
## Required outputs
|
||||
|
||||
Run this finish sequence after Approval readiness passes. The reference sections
|
||||
below supply content, formats and commands for the named step; they do not start
|
||||
another review cycle.
|
||||
Run this finish sequence after Approval readiness passes. Use the references
|
||||
below for each step, not as another review cycle.
|
||||
|
||||
On recovery, resume at the failed step. Reuse a successful Review Log for
|
||||
unchanged saved outputs; changed outputs must pass steps 1–4 again.
|
||||
For recovery or changed outputs, use the entrypoint's **Recovery routing**.
|
||||
|
||||
1. **Prepare the review body.** Use the output reference below to complete the
|
||||
working plan, Implementation Tasks and Completion summary. Derive unresolved
|
||||
@@ -452,19 +456,15 @@ unchanged saved outputs; changed outputs must pass steps 1–4 again.
|
||||
4. **Publish.** Display the Review Readiness Dashboard, then present the saved
|
||||
Completion summary to the user.
|
||||
5. **Choose navigation.** Use Next Steps — Review Chaining and wait for its answer.
|
||||
Navigation grants no implementation authority. If a substantive change arises,
|
||||
resolve it through Decision procedure, repeat Approval readiness, and redo the
|
||||
affected outputs from step 1 through publication before asking navigation again.
|
||||
Navigation grants no implementation authority. A substantive change follows
|
||||
**Recovery routing → Late change or missing work** before navigation resumes.
|
||||
6. **Finish.** Run Learning hooks, then return to the entrypoint's Section
|
||||
self-check and read-only EXIT PLAN MODE GATE. Run these checks in every host
|
||||
mode. Brain Calibration Write-Back is one gated Learning hook. Only after
|
||||
both pass, run success telemetry and cache refresh; call ExitPlanMode only in
|
||||
host plan mode.
|
||||
mode; its final instructions govern telemetry, cache refresh and exit.
|
||||
|
||||
### Output reference — review body
|
||||
|
||||
Keep the working plan, findings, ledger and the sections below together in the
|
||||
report file. Place `Suppressed findings` as a body appendix before the terminal
|
||||
Place `Suppressed findings` as a body appendix before the terminal
|
||||
`## GSTACK REVIEW REPORT`; nothing follows that terminal report.
|
||||
|
||||
### "NOT in scope" section
|
||||
@@ -571,9 +571,6 @@ without adding or strengthening them in the question or descriptions. A test
|
||||
required before editing one function does not make every independent lane wait.
|
||||
A next-step answer approves no implementation change.
|
||||
|
||||
For a substantive late change, follow the repeat path in finish step 5. Refresh
|
||||
affected tasks, dependencies and parallelization along with the other outputs.
|
||||
|
||||
## Learning hooks
|
||||
|
||||
In finish step 6, keep the working plan/approvals fixed. Review operational learnings
|
||||
|
||||
Reference in New Issue
Block a user