From 56a8ea215a130d37bf769a32c4fefb2910bc050b Mon Sep 17 00:00:00 2001 From: Greg Jackson Date: Sun, 15 Mar 2026 00:40:06 +0000 Subject: [PATCH] feat: persist review artifacts and cross-session handoff plan-ceo-review, plan-eng-review, and review now save their structured outputs to .gstack/reviews/ after each run. A rolling HANDOFF.md aggregates the most recent review of each type into a session-bridging document. ship reads HANDOFF.md during pre-flight and surfaces planning context in the PR body. Closes #6 Co-Authored-By: Claude Opus 4.6 (1M context) --- plan-ceo-review/SKILL.md | 67 +++++++++++++++++++++++++++++++++++ plan-ceo-review/SKILL.md.tmpl | 67 +++++++++++++++++++++++++++++++++++ plan-eng-review/SKILL.md | 65 +++++++++++++++++++++++++++++++++ plan-eng-review/SKILL.md.tmpl | 65 +++++++++++++++++++++++++++++++++ review/SKILL.md | 58 ++++++++++++++++++++++++++++++ review/SKILL.md.tmpl | 58 ++++++++++++++++++++++++++++++ ship/SKILL.md | 14 ++++++++ ship/SKILL.md.tmpl | 14 ++++++++ 8 files changed, 408 insertions(+) diff --git a/plan-ceo-review/SKILL.md b/plan-ceo-review/SKILL.md index e2e2395..e770487 100644 --- a/plan-ceo-review/SKILL.md +++ b/plan-ceo-review/SKILL.md @@ -456,6 +456,73 @@ List every ASCII diagram in files this plan touches. Still accurate? ### Unresolved Decisions If any AskUserQuestion goes unanswered, note it here. Never silently default. +## Save Review Artifacts + +After the review is complete, save the full review for future sessions. + +### Write archive files + +```bash +mkdir -p .gstack/reviews +SEQ=$(ls .gstack/reviews/plan-ceo-$(date +%Y-%m-%d)-*.json 2>/dev/null | wc -l | tr -d ' ') +SEQ=$((SEQ + 1)) +DATE=$(date +%Y-%m-%d) +``` + +Write the review outputs to `.gstack/reviews/plan-ceo-{DATE}-{SEQ}.md` containing: +* Completion summary table +* Error & rescue registry +* Failure modes registry +* "NOT in scope", "What already exists", "Dream state delta" sections +* All diagrams produced +* TODOS.md items proposed and user decisions +* Unresolved decisions + +Write structured JSON to `.gstack/reviews/plan-ceo-{DATE}-{SEQ}.json`: +```json +{ + "skill": "plan-ceo-review", + "date": "{DATE}", + "seq": {SEQ}, + "mode": "EXPANSION|HOLD|REDUCTION", + "completion_summary": "...", + "error_rescue_registry": [...], + "failure_modes": [...], + "not_in_scope": [...], + "what_already_exists": [...], + "dream_state_delta": "...", + "todos": [...], + "unresolved_decisions": [...], + "diagrams": [...] +} +``` + +### Regenerate HANDOFF.md + +Read the most recent archive of each type from `.gstack/reviews/` (most recent `plan-ceo-*.json`, `plan-eng-*.json`, `review-*.json`). Combine them into `.gstack/HANDOFF.md`: + +```markdown +# Handoff — {DATE} + +Generated by gstack. Read this before starting implementation. + +## CEO Review ({date from most recent plan-ceo archive}) + + +## Eng Review ({date from most recent plan-eng archive}) + + +## Code Review ({date from most recent review archive}) + + +## Open Items + +``` + +Only include sections for which archives exist. Omit sections with no prior reviews of that type. + +Output: `Review saved to .gstack/reviews/ and handoff regenerated at .gstack/HANDOFF.md.` + ## Formatting Rules * NUMBER issues (1, 2, 3...) and LETTERS for options (A, B, C...). * Label with NUMBER + LETTER (e.g., "3A", "3B"). diff --git a/plan-ceo-review/SKILL.md.tmpl b/plan-ceo-review/SKILL.md.tmpl index 0497de3..3415d79 100644 --- a/plan-ceo-review/SKILL.md.tmpl +++ b/plan-ceo-review/SKILL.md.tmpl @@ -447,6 +447,73 @@ List every ASCII diagram in files this plan touches. Still accurate? ### Unresolved Decisions If any AskUserQuestion goes unanswered, note it here. Never silently default. +## Save Review Artifacts + +After the review is complete, save the full review for future sessions. + +### Write archive files + +```bash +mkdir -p .gstack/reviews +SEQ=$(ls .gstack/reviews/plan-ceo-$(date +%Y-%m-%d)-*.json 2>/dev/null | wc -l | tr -d ' ') +SEQ=$((SEQ + 1)) +DATE=$(date +%Y-%m-%d) +``` + +Write the review outputs to `.gstack/reviews/plan-ceo-{DATE}-{SEQ}.md` containing: +* Completion summary table +* Error & rescue registry +* Failure modes registry +* "NOT in scope", "What already exists", "Dream state delta" sections +* All diagrams produced +* TODOS.md items proposed and user decisions +* Unresolved decisions + +Write structured JSON to `.gstack/reviews/plan-ceo-{DATE}-{SEQ}.json`: +```json +{ + "skill": "plan-ceo-review", + "date": "{DATE}", + "seq": {SEQ}, + "mode": "EXPANSION|HOLD|REDUCTION", + "completion_summary": "...", + "error_rescue_registry": [...], + "failure_modes": [...], + "not_in_scope": [...], + "what_already_exists": [...], + "dream_state_delta": "...", + "todos": [...], + "unresolved_decisions": [...], + "diagrams": [...] +} +``` + +### Regenerate HANDOFF.md + +Read the most recent archive of each type from `.gstack/reviews/` (most recent `plan-ceo-*.json`, `plan-eng-*.json`, `review-*.json`). Combine them into `.gstack/HANDOFF.md`: + +```markdown +# Handoff — {DATE} + +Generated by gstack. Read this before starting implementation. + +## CEO Review ({date from most recent plan-ceo archive}) + + +## Eng Review ({date from most recent plan-eng archive}) + + +## Code Review ({date from most recent review archive}) + + +## Open Items + +``` + +Only include sections for which archives exist. Omit sections with no prior reviews of that type. + +Output: `Review saved to .gstack/reviews/ and handoff regenerated at .gstack/HANDOFF.md.` + ## Formatting Rules * NUMBER issues (1, 2, 3...) and LETTERS for options (A, B, C...). * Label with NUMBER + LETTER (e.g., "3A", "3B"). diff --git a/plan-eng-review/SKILL.md b/plan-eng-review/SKILL.md index cf62a1d..393cae3 100644 --- a/plan-eng-review/SKILL.md +++ b/plan-eng-review/SKILL.md @@ -172,3 +172,68 @@ Check the git log for this branch. If there are prior commits suggesting a previ ## Unresolved decisions If the user does not respond to an AskUserQuestion or interrupts to move on, note which decisions were left unresolved. At the end of the review, list these as "Unresolved decisions that may bite you later" — never silently default to an option. + +## Save Review Artifacts + +After the review is complete, save the full review for future sessions. + +### Write archive files + +```bash +mkdir -p .gstack/reviews +SEQ=$(ls .gstack/reviews/plan-eng-$(date +%Y-%m-%d)-*.json 2>/dev/null | wc -l | tr -d ' ') +SEQ=$((SEQ + 1)) +DATE=$(date +%Y-%m-%d) +``` + +Write the review outputs to `.gstack/reviews/plan-eng-{DATE}-{SEQ}.md` containing: +* Completion summary +* Step 0 scope challenge and user's mode selection +* "NOT in scope" and "What already exists" sections +* All diagrams produced +* Failure modes and critical gaps +* TODOS.md items proposed and user decisions +* Unresolved decisions + +Write structured JSON to `.gstack/reviews/plan-eng-{DATE}-{SEQ}.json`: +```json +{ + "skill": "plan-eng-review", + "date": "{DATE}", + "seq": {SEQ}, + "mode": "REDUCTION|BIG_CHANGE|SMALL_CHANGE", + "completion_summary": "...", + "not_in_scope": [...], + "what_already_exists": [...], + "failure_modes": [...], + "todos": [...], + "unresolved_decisions": [...], + "diagrams": [...] +} +``` + +### Regenerate HANDOFF.md + +Read the most recent archive of each type from `.gstack/reviews/` (most recent `plan-ceo-*.json`, `plan-eng-*.json`, `review-*.json`). Combine them into `.gstack/HANDOFF.md`: + +```markdown +# Handoff — {DATE} + +Generated by gstack. Read this before starting implementation. + +## CEO Review ({date from most recent plan-ceo archive}) + + +## Eng Review ({date from most recent plan-eng archive}) + + +## Code Review ({date from most recent review archive}) + + +## Open Items + +``` + +Only include sections for which archives exist. Omit sections with no prior reviews of that type. + +Output: `Review saved to .gstack/reviews/ and handoff regenerated at .gstack/HANDOFF.md.` diff --git a/plan-eng-review/SKILL.md.tmpl b/plan-eng-review/SKILL.md.tmpl index 331ee1c..addbba6 100644 --- a/plan-eng-review/SKILL.md.tmpl +++ b/plan-eng-review/SKILL.md.tmpl @@ -163,3 +163,68 @@ Check the git log for this branch. If there are prior commits suggesting a previ ## Unresolved decisions If the user does not respond to an AskUserQuestion or interrupts to move on, note which decisions were left unresolved. At the end of the review, list these as "Unresolved decisions that may bite you later" — never silently default to an option. + +## Save Review Artifacts + +After the review is complete, save the full review for future sessions. + +### Write archive files + +```bash +mkdir -p .gstack/reviews +SEQ=$(ls .gstack/reviews/plan-eng-$(date +%Y-%m-%d)-*.json 2>/dev/null | wc -l | tr -d ' ') +SEQ=$((SEQ + 1)) +DATE=$(date +%Y-%m-%d) +``` + +Write the review outputs to `.gstack/reviews/plan-eng-{DATE}-{SEQ}.md` containing: +* Completion summary +* Step 0 scope challenge and user's mode selection +* "NOT in scope" and "What already exists" sections +* All diagrams produced +* Failure modes and critical gaps +* TODOS.md items proposed and user decisions +* Unresolved decisions + +Write structured JSON to `.gstack/reviews/plan-eng-{DATE}-{SEQ}.json`: +```json +{ + "skill": "plan-eng-review", + "date": "{DATE}", + "seq": {SEQ}, + "mode": "REDUCTION|BIG_CHANGE|SMALL_CHANGE", + "completion_summary": "...", + "not_in_scope": [...], + "what_already_exists": [...], + "failure_modes": [...], + "todos": [...], + "unresolved_decisions": [...], + "diagrams": [...] +} +``` + +### Regenerate HANDOFF.md + +Read the most recent archive of each type from `.gstack/reviews/` (most recent `plan-ceo-*.json`, `plan-eng-*.json`, `review-*.json`). Combine them into `.gstack/HANDOFF.md`: + +```markdown +# Handoff — {DATE} + +Generated by gstack. Read this before starting implementation. + +## CEO Review ({date from most recent plan-ceo archive}) + + +## Eng Review ({date from most recent plan-eng archive}) + + +## Code Review ({date from most recent review archive}) + + +## Open Items + +``` + +Only include sections for which archives exist. Omit sections with no prior reviews of that type. + +Output: `Review saved to .gstack/reviews/ and handoff regenerated at .gstack/HANDOFF.md.` diff --git a/review/SKILL.md b/review/SKILL.md index e3d2e2c..255b876 100644 --- a/review/SKILL.md +++ b/review/SKILL.md @@ -115,6 +115,64 @@ After outputting your own findings, if Greptile comments were classified in Step --- +## Step 6: Save Review Artifacts + +After findings are output and any critical issues resolved, save the review for future sessions. + +```bash +mkdir -p .gstack/reviews +SEQ=$(ls .gstack/reviews/review-$(date +%Y-%m-%d)-*.json 2>/dev/null | wc -l | tr -d ' ') +SEQ=$((SEQ + 1)) +DATE=$(date +%Y-%m-%d) +``` + +Write the full review to `.gstack/reviews/review-{DATE}-{SEQ}.md` containing: +- Branch name and commit range reviewed +- All findings (critical and informational) with file:line references +- Greptile summary and comment resolutions (if applicable) +- Resolution status for each critical issue (fixed / acknowledged / false positive) + +Write structured JSON to `.gstack/reviews/review-{DATE}-{SEQ}.json`: +```json +{ + "skill": "review", + "date": "{DATE}", + "seq": {SEQ}, + "branch": "...", + "critical_count": 0, + "informational_count": 0, + "findings": [...], + "greptile_summary": "...", + "resolutions": [...] +} +``` + +Regenerate `.gstack/HANDOFF.md` by reading the most recent archive of each type from `.gstack/reviews/` (most recent `plan-ceo-*.json`, `plan-eng-*.json`, `review-*.json`) and combining them: + +```markdown +# Handoff — {DATE} + +Generated by gstack. Read this before starting implementation. + +## CEO Review ({date from most recent plan-ceo archive}) + + +## Eng Review ({date from most recent plan-eng archive}) + + +## Code Review ({date from most recent review archive}) + + +## Open Items + +``` + +Only include sections for which archives exist. Omit sections with no prior reviews of that type. + +Output: `Review saved to .gstack/reviews/ and handoff regenerated at .gstack/HANDOFF.md.` + +--- + ## Important Rules - **Read the FULL diff before commenting.** Do not flag issues already addressed in the diff. diff --git a/review/SKILL.md.tmpl b/review/SKILL.md.tmpl index 365e528..71e9a07 100644 --- a/review/SKILL.md.tmpl +++ b/review/SKILL.md.tmpl @@ -106,6 +106,64 @@ After outputting your own findings, if Greptile comments were classified in Step --- +## Step 6: Save Review Artifacts + +After findings are output and any critical issues resolved, save the review for future sessions. + +```bash +mkdir -p .gstack/reviews +SEQ=$(ls .gstack/reviews/review-$(date +%Y-%m-%d)-*.json 2>/dev/null | wc -l | tr -d ' ') +SEQ=$((SEQ + 1)) +DATE=$(date +%Y-%m-%d) +``` + +Write the full review to `.gstack/reviews/review-{DATE}-{SEQ}.md` containing: +- Branch name and commit range reviewed +- All findings (critical and informational) with file:line references +- Greptile summary and comment resolutions (if applicable) +- Resolution status for each critical issue (fixed / acknowledged / false positive) + +Write structured JSON to `.gstack/reviews/review-{DATE}-{SEQ}.json`: +```json +{ + "skill": "review", + "date": "{DATE}", + "seq": {SEQ}, + "branch": "...", + "critical_count": 0, + "informational_count": 0, + "findings": [...], + "greptile_summary": "...", + "resolutions": [...] +} +``` + +Regenerate `.gstack/HANDOFF.md` by reading the most recent archive of each type from `.gstack/reviews/` (most recent `plan-ceo-*.json`, `plan-eng-*.json`, `review-*.json`) and combining them: + +```markdown +# Handoff — {DATE} + +Generated by gstack. Read this before starting implementation. + +## CEO Review ({date from most recent plan-ceo archive}) + + +## Eng Review ({date from most recent plan-eng archive}) + + +## Code Review ({date from most recent review archive}) + + +## Open Items + +``` + +Only include sections for which archives exist. Omit sections with no prior reviews of that type. + +Output: `Review saved to .gstack/reviews/ and handoff regenerated at .gstack/HANDOFF.md.` + +--- + ## Important Rules - **Read the FULL diff before commenting.** Do not flag issues already addressed in the diff. diff --git a/ship/SKILL.md b/ship/SKILL.md index 32a917d..a803780 100644 --- a/ship/SKILL.md +++ b/ship/SKILL.md @@ -53,6 +53,16 @@ You are running the `/ship` workflow. This is a **non-interactive, fully automat 3. Run `git diff main...HEAD --stat` and `git log main..HEAD --oneline` to understand what's being shipped. +4. **Load planning context:** + +**If `.gstack/HANDOFF.md` does not exist:** Skip silently. + +**If it exists:** Read it. Use the planning context to enrich the PR body in Step 8 — add a "Planning Context" section summarizing key decisions, scope exclusions, and unresolved items from prior reviews. + +```bash +[ -f .gstack/HANDOFF.md ] && cat .gstack/HANDOFF.md +``` + --- ## Step 2: Merge origin/main (BEFORE tests) @@ -324,6 +334,10 @@ gh pr create --title ": " --body "$(cat <<'EOF' ## Eval Results +## Planning Context + + + ## Greptile Review diff --git a/ship/SKILL.md.tmpl b/ship/SKILL.md.tmpl index ed525cd..f1fef7f 100644 --- a/ship/SKILL.md.tmpl +++ b/ship/SKILL.md.tmpl @@ -44,6 +44,16 @@ You are running the `/ship` workflow. This is a **non-interactive, fully automat 3. Run `git diff main...HEAD --stat` and `git log main..HEAD --oneline` to understand what's being shipped. +4. **Load planning context:** + +**If `.gstack/HANDOFF.md` does not exist:** Skip silently. + +**If it exists:** Read it. Use the planning context to enrich the PR body in Step 8 — add a "Planning Context" section summarizing key decisions, scope exclusions, and unresolved items from prior reviews. + +```bash +[ -f .gstack/HANDOFF.md ] && cat .gstack/HANDOFF.md +``` + --- ## Step 2: Merge origin/main (BEFORE tests) @@ -315,6 +325,10 @@ gh pr create --title ": " --body "$(cat <<'EOF' ## Eval Results +## Planning Context + + + ## Greptile Review