Skip to content

feat: /brainstorm + /debug skills, process discipline across all skills (v0.6.0)#103

Open
garrytan wants to merge 10 commits intomainfrom
garrytan/better-process
Open

feat: /brainstorm + /debug skills, process discipline across all skills (v0.6.0)#103
garrytan wants to merge 10 commits intomainfrom
garrytan/better-process

Conversation

@garrytan
Copy link
Owner

Summary

  • New /brainstorm skill — Socratic design exploration before planning. Asks clarifying questions, challenges premises, forces 2-3 implementation alternatives, writes design doc artifact to ~/.gstack/projects/. Design docs auto-discovered by downstream skills (/plan-ceo-review, /plan-eng-review). Includes design lineage tracking (Supersedes: field) and cross-team keyword-based design discovery.
  • New /debug skill — Systematic root-cause debugging. Iron Law: no fixes without investigation. Pattern analysis, hypothesis testing, 3-strike escalation rule. Structured DEBUG REPORT output.
  • Escalation protocol in preamble — All skills now report DONE/DONE_WITH_CONCERNS/BLOCKED/NEEDS_CONTEXT and have explicit escalation instructions.
  • /ship verification gate (Step 6.5) — Re-verify tests before pushing if code changed during review fixes.
  • /review scope drift detection (Step 1.5) — Compares diff against TODOS.md/commit messages, flags scope creep and missing requirements.
  • /review verification of claims — Every claim must cite evidence (line references, test names).
  • /plan-ceo-review mandatory alternatives (Step 0C-bis) — 2-3 implementation approaches before mode selection.
  • Design doc lookup in plan-ceo-review and plan-eng-review pre-review audits (branch-filtered with fallback).
  • Branch name sanitization — fixes / in branch names breaking artifact filenames (brainstorm + plan-eng-review test plan).

Pre-Landing Review

Pre-Landing Review: No issues found. All changes are prompt engineering (Markdown templates + TypeScript test assertions).

Eval Results

No prompt-related files changed — evals skipped.

TODOS

  • Added: Design docs → Supabase team store sync (P2, depends on team-supabase-store)
  • Added: /plan-design-review skill (P2, depends on design branch)

Test plan

  • All tests pass (259 tests, 0 failures)
  • gen:skill-docs generates all 13 skills including 2 new ones

🤖 Generated with Claude Code

garrytan and others added 10 commits March 16, 2026 10:09
…ED/NEEDS_CONTEXT

Every skill now reports completion status (DONE, DONE_WITH_CONCERNS, BLOCKED,
NEEDS_CONTEXT) and has escalation rules: 3 failed attempts → STOP, security
uncertainty → STOP, scope exceeds verification → STOP.

"It is always OK to stop and say 'this is too hard for me.'"

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
…sh evidence

Before pushing, re-verify tests if code changed during review fixes.
Rationalization prevention: "Should work now" → RUN IT.
"I'm confident" → Confidence is not evidence.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Step 1.5: Before reviewing code quality, check if the diff matches stated
intent. Flags scope creep and missing requirements (INFORMATIONAL).

Step 5 addition: Every review claim must cite evidence — "this pattern is
safe" needs a line reference, "tests cover this" needs a test name.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
…lan-ceo-review

Step 0C-bis: Every plan must consider 2-3 approaches (minimal viable vs ideal
architecture) before mode selection. RECOMMENDATION required.

Pre-Review System Audit now checks ~/.gstack/projects/ for /brainstorm design
docs (branch-filtered with fallback).

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
…ation

Step 0 now checks ~/.gstack/projects/ for /brainstorm design docs
(branch-filtered with fallback, reads Supersedes: for revision context).

Fix: branch names with '/' (e.g. garrytan/better-process) now get
sanitized via tr '/' '-' in test plan artifact filenames.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
/brainstorm: Socratic design exploration before planning. Context gathering,
clarifying questions (smart-skip), related design discovery (keyword grep),
premise challenge, forced alternatives, design doc artifact with lineage
tracking (Supersedes: field). Writes to ~/.gstack/projects/$SLUG/.

/debug: Systematic root-cause debugging. Iron Law: no fixes without root
cause investigation. Pattern analysis, hypothesis testing with 3-strike
escalation, structured DEBUG REPORT output.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Add brainstorm + debug to skillsWithUpdateCheck and skillsWithPreamble arrays.
Add structural tests: brainstorm (Phase 1-6, Design Doc, Supersedes, Smart-skip),
debug (Iron Law, Root Cause, Pattern Analysis, Hypothesis, DEBUG REPORT, 3-strike).
Add escalation protocol tests (DONE_WITH_CONCERNS, BLOCKED, NEEDS_CONTEXT) for
all preamble skills.

Also: 2 new TODOs (design docs → Supabase sync, /plan-design-review skill),
update CLAUDE.md project structure with new skill directories.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
…ection)

Merge origin/main which added:
- BASE_BRANCH_DETECT placeholder + dynamic branch detection in all skills
- Updated contributor mode (reflection-based, 0-10 rating)
- Async await wrapping in browse js/eval commands
- Hardcoded-main regression test

Resolved conflicts:
- VERSION: keep 0.6.0 (our version, above 0.4.2)
- CHANGELOG: both entries preserved (0.6.0 above 0.4.2)
- gen-skill-docs.ts: keep main's updated contributor mode, add our escalation protocol
- review/SKILL.md.tmpl: fix hardcoded 'origin/main' in Step 1.5 to use origin/<base>

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Merge origin/main which added:
- v0.4.3: /document-release skill, simplified AskUserQuestion (always ELI16),
  runtime branch detection via _BRANCH preamble variable
- v0.4.4: 60-min update check TTL, --force flag for gstack-update-check

Resolved conflicts:
- VERSION: keep 0.6.0 (our version, above 0.4.4)
- CHANGELOG: all entries preserved (0.6.0 > 0.4.4 > 0.4.3 > 0.4.2)
- TODOS.md: keep both sections (Brainstorm/Design + Document-Release)
- test/skill-validation.test.ts: include all three new skills in arrays
  (brainstorm, debug, document-release)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant