diff --git a/plan-ceo-review/SKILL.md b/plan-ceo-review/SKILL.md index c82753a2..c3c9428e 100644 --- a/plan-ceo-review/SKILL.md +++ b/plan-ceo-review/SKILL.md @@ -73,6 +73,31 @@ Then run: `mkdir -p ~/.gstack/contributor-logs && open ~/.gstack/contributor-log Slug: lowercase, hyphens, max 60 chars (e.g. `browse-snapshot-ref-gap`). Skip if file already exists. Max 3 reports per session. File inline and continue — don't stop the workflow. Tell user: "Filed gstack field report: {title}" +## Completion Status Protocol + +When completing a skill workflow, report status using one of: +- **DONE** — All steps completed successfully. Evidence provided for each claim. +- **DONE_WITH_CONCERNS** — Completed, but with issues the user should know about. List each concern. +- **BLOCKED** — Cannot proceed. State what is blocking and what was tried. +- **NEEDS_CONTEXT** — Missing information required to continue. State exactly what you need. + +### Escalation + +It is always OK to stop and say "this is too hard for me" or "I'm not confident in this result." + +Bad work is worse than no work. You will not be penalized for escalating. +- If you have attempted a task 3 times without success, STOP and escalate. +- If you are uncertain about a security-sensitive change, STOP and escalate. +- If the scope of work exceeds what you can verify, STOP and escalate. + +Escalation format: +``` +STATUS: BLOCKED | NEEDS_CONTEXT +REASON: [1-2 sentences] +ATTEMPTED: [what you tried] +RECOMMENDATION: [what the user should do next] +``` + # Mega Plan Review Mode ## Philosophy @@ -122,7 +147,19 @@ git stash list # Any stashed work grep -r "TODO\|FIXME\|HACK\|XXX" --include="*.rb" --include="*.js" -l find . -name "*.rb" -newer Gemfile.lock | head -20 # Recently touched files ``` -Then read CLAUDE.md, TODOS.md, and any existing architecture docs. When reading TODOS.md, specifically: +Then read CLAUDE.md, TODOS.md, and any existing architecture docs. + +**Design doc check:** +```bash +SLUG=$(~/.claude/skills/gstack/browse/bin/remote-slug 2>/dev/null || basename "$(git rev-parse --show-toplevel 2>/dev/null || pwd)") +BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null | tr '/' '-' || echo 'no-branch') +DESIGN=$(ls -t ~/.gstack/projects/$SLUG/*-$BRANCH-design-*.md 2>/dev/null | head -1) +[ -z "$DESIGN" ] && DESIGN=$(ls -t ~/.gstack/projects/$SLUG/*-design-*.md 2>/dev/null | head -1) +[ -n "$DESIGN" ] && echo "Design doc found: $DESIGN" || echo "No design doc found" +``` +If a design doc exists (from `/brainstorm`), read it. Use it as the source of truth for the problem statement, constraints, and chosen approach. If it has a `Supersedes:` field, note that this is a revised design. + +When reading TODOS.md, specifically: * Note any TODOs this plan touches, blocks, or unlocks * Check if deferred work from prior reviews relates to this plan * Flag dependencies: does this plan enable or depend on deferred items? @@ -159,6 +196,36 @@ Describe the ideal end state of this system 12 months from now. Does this plan m [describe] ---> [describe delta] ---> [describe target] ``` +### 0C-bis. Implementation Alternatives (MANDATORY) + +Before selecting a mode (0F), produce 2-3 distinct implementation approaches. This is NOT optional — every plan must consider alternatives. + +For each approach: +``` +APPROACH A: [Name] + Summary: [1-2 sentences] + Effort: [S/M/L/XL] + Risk: [Low/Med/High] + Pros: [2-3 bullets] + Cons: [2-3 bullets] + Reuses: [existing code/patterns leveraged] + +APPROACH B: [Name] + ... + +APPROACH C: [Name] (optional — include if a meaningfully different path exists) + ... +``` + +**RECOMMENDATION:** Choose [X] because [one-line reason mapped to engineering preferences]. + +Rules: +- At least 2 approaches required. 3 preferred for non-trivial plans. +- One approach must be the "minimal viable" (fewest files, smallest diff). +- One approach must be the "ideal architecture" (best long-term trajectory). +- If only one approach exists, explain concretely why alternatives were eliminated. +- Do NOT proceed to mode selection (0F) without user approval of the chosen approach. + ### 0D. Mode-Specific Analysis **For SCOPE EXPANSION** — run all three: 1. 10x check: What's the version that's 10x more ambitious and delivers 10x more value for 2x the effort? Describe it concretely. @@ -196,6 +263,8 @@ Context-dependent defaults: * Plan touching >15 files → suggest REDUCTION unless user pushes back * User says "go big" / "ambitious" / "cathedral" → EXPANSION, no question +After mode is selected, confirm which implementation approach (from 0C-bis) applies under the chosen mode. EXPANSION may favor the ideal architecture approach; REDUCTION may favor the minimal viable approach. + Once selected, commit fully. Do not silently drift. **STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues or fix is obvious, state what you'll do and move on — don't waste a question. Do NOT proceed until user responds. diff --git a/plan-ceo-review/SKILL.md.tmpl b/plan-ceo-review/SKILL.md.tmpl index ef14a281..400fb579 100644 --- a/plan-ceo-review/SKILL.md.tmpl +++ b/plan-ceo-review/SKILL.md.tmpl @@ -65,7 +65,19 @@ git stash list # Any stashed work grep -r "TODO\|FIXME\|HACK\|XXX" --include="*.rb" --include="*.js" -l find . -name "*.rb" -newer Gemfile.lock | head -20 # Recently touched files ``` -Then read CLAUDE.md, TODOS.md, and any existing architecture docs. When reading TODOS.md, specifically: +Then read CLAUDE.md, TODOS.md, and any existing architecture docs. + +**Design doc check:** +```bash +SLUG=$(~/.claude/skills/gstack/browse/bin/remote-slug 2>/dev/null || basename "$(git rev-parse --show-toplevel 2>/dev/null || pwd)") +BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null | tr '/' '-' || echo 'no-branch') +DESIGN=$(ls -t ~/.gstack/projects/$SLUG/*-$BRANCH-design-*.md 2>/dev/null | head -1) +[ -z "$DESIGN" ] && DESIGN=$(ls -t ~/.gstack/projects/$SLUG/*-design-*.md 2>/dev/null | head -1) +[ -n "$DESIGN" ] && echo "Design doc found: $DESIGN" || echo "No design doc found" +``` +If a design doc exists (from `/brainstorm`), read it. Use it as the source of truth for the problem statement, constraints, and chosen approach. If it has a `Supersedes:` field, note that this is a revised design. + +When reading TODOS.md, specifically: * Note any TODOs this plan touches, blocks, or unlocks * Check if deferred work from prior reviews relates to this plan * Flag dependencies: does this plan enable or depend on deferred items? @@ -102,6 +114,36 @@ Describe the ideal end state of this system 12 months from now. Does this plan m [describe] ---> [describe delta] ---> [describe target] ``` +### 0C-bis. Implementation Alternatives (MANDATORY) + +Before selecting a mode (0F), produce 2-3 distinct implementation approaches. This is NOT optional — every plan must consider alternatives. + +For each approach: +``` +APPROACH A: [Name] + Summary: [1-2 sentences] + Effort: [S/M/L/XL] + Risk: [Low/Med/High] + Pros: [2-3 bullets] + Cons: [2-3 bullets] + Reuses: [existing code/patterns leveraged] + +APPROACH B: [Name] + ... + +APPROACH C: [Name] (optional — include if a meaningfully different path exists) + ... +``` + +**RECOMMENDATION:** Choose [X] because [one-line reason mapped to engineering preferences]. + +Rules: +- At least 2 approaches required. 3 preferred for non-trivial plans. +- One approach must be the "minimal viable" (fewest files, smallest diff). +- One approach must be the "ideal architecture" (best long-term trajectory). +- If only one approach exists, explain concretely why alternatives were eliminated. +- Do NOT proceed to mode selection (0F) without user approval of the chosen approach. + ### 0D. Mode-Specific Analysis **For SCOPE EXPANSION** — run all three: 1. 10x check: What's the version that's 10x more ambitious and delivers 10x more value for 2x the effort? Describe it concretely. @@ -139,6 +181,8 @@ Context-dependent defaults: * Plan touching >15 files → suggest REDUCTION unless user pushes back * User says "go big" / "ambitious" / "cathedral" → EXPANSION, no question +After mode is selected, confirm which implementation approach (from 0C-bis) applies under the chosen mode. EXPANSION may favor the ideal architecture approach; REDUCTION may favor the minimal viable approach. + Once selected, commit fully. Do not silently drift. **STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues or fix is obvious, state what you'll do and move on — don't waste a question. Do NOT proceed until user responds.