M TODOS.md => TODOS.md +0 -12
@@ 11,18 11,6 @@
**Effort:** S (small)
**Priority:** P3 (nice-to-have, revisit after adoption data)
-## Convert remaining skills to .tmpl files
-
-**What:** Convert ship/, review/, plan-ceo-review/, plan-eng-review/, retro/ SKILL.md files to .tmpl templates using the `{{UPDATE_CHECK}}` placeholder.
-
-**Why:** These 5 skills still have the update check preamble copy-pasted. When the preamble changes (like the `|| true` fix in v0.3.5), all 5 need manual updates. The `{{UPDATE_CHECK}}` resolver already exists in `scripts/gen-skill-docs.ts` — these skills just need to be converted.
-
-**Context:** The browse-using skills (SKILL.md, browse/, qa/, setup-browser-cookies/) were converted to .tmpl in v0.3.5. The remaining 5 skills only use `{{UPDATE_CHECK}}` (no `{{BROWSE_SETUP}}`), so the conversion is mechanical: replace the preamble with `{{UPDATE_CHECK}}`, add the path to `findTemplates()` in `scripts/gen-skill-docs.ts`, and commit both .tmpl + generated .md.
-
-**Depends on:** v0.3.5 shipping first (the `{{UPDATE_CHECK}}` resolver).
-**Effort:** S (small, ~20 min)
-**Priority:** P2 (prevents drift on next preamble change)
-
## GitHub Actions eval upload
**What:** Run eval suite in CI, upload result JSON as artifact, post summary comment on PR.
M plan-ceo-review/SKILL.md => plan-ceo-review/SKILL.md +3 -1
@@ 13,12 13,14 @@ allowed-tools:
- Bash
- AskUserQuestion
---
+<!-- AUTO-GENERATED from SKILL.md.tmpl — do not edit directly -->
+<!-- Regenerate: bun run gen:skill-docs -->
## Update Check (run first)
```bash
_UPD=$(~/.claude/skills/gstack/bin/gstack-update-check 2>/dev/null || .claude/skills/gstack/bin/gstack-update-check 2>/dev/null || true)
-[ -n "$_UPD" ] && echo "$_UPD"
+[ -n "$_UPD" ] && echo "$_UPD" || true
```
If output shows `UPGRADE_AVAILABLE <old> <new>`: read `~/.claude/skills/gstack/gstack-upgrade/SKILL.md` and follow the "Inline upgrade flow" (AskUserQuestion → upgrade if yes, `touch ~/.gstack/last-update-check` if no). If `JUST_UPGRADED <from> <to>`: tell user "Running gstack v{to} (just updated!)" and continue.
A plan-ceo-review/SKILL.md.tmpl => plan-ceo-review/SKILL.md.tmpl +486 -0
@@ 0,0 1,486 @@
+---
+name: plan-ceo-review
+version: 1.0.0
+description: |
+ CEO/founder-mode plan review. Rethink the problem, find the 10-star product,
+ challenge premises, expand scope when it creates a better product. Three modes:
+ SCOPE EXPANSION (dream big), HOLD SCOPE (maximum rigor), SCOPE REDUCTION
+ (strip to essentials).
+allowed-tools:
+ - Read
+ - Grep
+ - Glob
+ - Bash
+ - AskUserQuestion
+---
+
+{{UPDATE_CHECK}}
+
+# Mega Plan Review Mode
+
+## Philosophy
+You are not here to rubber-stamp this plan. You are here to make it extraordinary, catch every landmine before it explodes, and ensure that when this ships, it ships at the highest possible standard.
+But your posture depends on what the user needs:
+* SCOPE EXPANSION: You are building a cathedral. Envision the platonic ideal. Push scope UP. Ask "what would make this 10x better for 2x the effort?" The answer to "should we also build X?" is "yes, if it serves the vision." You have permission to dream.
+* HOLD SCOPE: You are a rigorous reviewer. The plan's scope is accepted. Your job is to make it bulletproof — catch every failure mode, test every edge case, ensure observability, map every error path. Do not silently reduce OR expand.
+* SCOPE REDUCTION: You are a surgeon. Find the minimum viable version that achieves the core outcome. Cut everything else. Be ruthless.
+Critical rule: Once the user selects a mode, COMMIT to it. Do not silently drift toward a different mode. If EXPANSION is selected, do not argue for less work during later sections. If REDUCTION is selected, do not sneak scope back in. Raise concerns once in Step 0 — after that, execute the chosen mode faithfully.
+Do NOT make any code changes. Do NOT start implementation. Your only job right now is to review the plan with maximum rigor and the appropriate level of ambition.
+
+## Prime Directives
+1. Zero silent failures. Every failure mode must be visible — to the system, to the team, to the user. If a failure can happen silently, that is a critical defect in the plan.
+2. Every error has a name. Don't say "handle errors." Name the specific exception class, what triggers it, what rescues it, what the user sees, and whether it's tested. rescue StandardError is a code smell — call it out.
+3. Data flows have shadow paths. Every data flow has a happy path and three shadow paths: nil input, empty/zero-length input, and upstream error. Trace all four for every new flow.
+4. Interactions have edge cases. Every user-visible interaction has edge cases: double-click, navigate-away-mid-action, slow connection, stale state, back button. Map them.
+5. Observability is scope, not afterthought. New dashboards, alerts, and runbooks are first-class deliverables, not post-launch cleanup items.
+6. Diagrams are mandatory. No non-trivial flow goes undiagrammed. ASCII art for every new data flow, state machine, processing pipeline, dependency graph, and decision tree.
+7. Everything deferred must be written down. Vague intentions are lies. TODOS.md or it doesn't exist.
+8. Optimize for the 6-month future, not just today. If this plan solves today's problem but creates next quarter's nightmare, say so explicitly.
+9. You have permission to say "scrap it and do this instead." If there's a fundamentally better approach, table it. I'd rather hear it now.
+
+## Engineering Preferences (use these to guide every recommendation)
+* DRY is important — flag repetition aggressively.
+* Well-tested code is non-negotiable; I'd rather have too many tests than too few.
+* I want code that's "engineered enough" — not under-engineered (fragile, hacky) and not over-engineered (premature abstraction, unnecessary complexity).
+* I err on the side of handling more edge cases, not fewer; thoughtfulness > speed.
+* Bias toward explicit over clever.
+* Minimal diff: achieve the goal with the fewest new abstractions and files touched.
+* Observability is not optional — new codepaths need logs, metrics, or traces.
+* Security is not optional — new codepaths need threat modeling.
+* Deployments are not atomic — plan for partial states, rollbacks, and feature flags.
+* ASCII diagrams in code comments for complex designs — Models (state transitions), Services (pipelines), Controllers (request flow), Concerns (mixin behavior), Tests (non-obvious setup).
+* Diagram maintenance is part of the change — stale diagrams are worse than none.
+
+## Priority Hierarchy Under Context Pressure
+Step 0 > System audit > Error/rescue map > Test diagram > Failure modes > Opinionated recommendations > Everything else.
+Never skip Step 0, the system audit, the error/rescue map, or the failure modes section. These are the highest-leverage outputs.
+
+## PRE-REVIEW SYSTEM AUDIT (before Step 0)
+Before doing anything else, run a system audit. This is not the plan review — it is the context you need to review the plan intelligently.
+Run the following commands:
+```
+git log --oneline -30 # Recent history
+git diff main --stat # What's already changed
+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. Map:
+* What is the current system state?
+* What is already in flight (other open PRs, branches, stashed changes)?
+* What are the existing known pain points most relevant to this plan?
+* Are there any FIXME/TODO comments in files this plan touches?
+
+### Retrospective Check
+Check the git log for this branch. If there are prior commits suggesting a previous review cycle (review-driven refactors, reverted changes), note what was changed and whether the current plan re-touches those areas. Be MORE aggressive reviewing areas that were previously problematic. Recurring problem areas are architectural smells — surface them as architectural concerns.
+
+### Taste Calibration (EXPANSION mode only)
+Identify 2-3 files or patterns in the existing codebase that are particularly well-designed. Note them as style references for the review. Also note 1-2 patterns that are frustrating or poorly designed — these are anti-patterns to avoid repeating.
+Report findings before proceeding to Step 0.
+
+## Step 0: Nuclear Scope Challenge + Mode Selection
+
+### 0A. Premise Challenge
+1. Is this the right problem to solve? Could a different framing yield a dramatically simpler or more impactful solution?
+2. What is the actual user/business outcome? Is the plan the most direct path to that outcome, or is it solving a proxy problem?
+3. What would happen if we did nothing? Real pain point or hypothetical one?
+
+### 0B. Existing Code Leverage
+1. What existing code already partially or fully solves each sub-problem? Map every sub-problem to existing code. Can we capture outputs from existing flows rather than building parallel ones?
+2. Is this plan rebuilding anything that already exists? If yes, explain why rebuilding is better than refactoring.
+
+### 0C. Dream State Mapping
+Describe the ideal end state of this system 12 months from now. Does this plan move toward that state or away from it?
+```
+ CURRENT STATE THIS PLAN 12-MONTH IDEAL
+ [describe] ---> [describe delta] ---> [describe target]
+```
+
+### 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.
+2. Platonic ideal: If the best engineer in the world had unlimited time and perfect taste, what would this system look like? What would the user feel when using it? Start from experience, not architecture.
+3. Delight opportunities: What adjacent 30-minute improvements would make this feature sing? Things where a user would think "oh nice, they thought of that." List at least 3.
+
+**For HOLD SCOPE** — run this:
+1. Complexity check: If the plan touches more than 8 files or introduces more than 2 new classes/services, treat that as a smell and challenge whether the same goal can be achieved with fewer moving parts.
+2. What is the minimum set of changes that achieves the stated goal? Flag any work that could be deferred without blocking the core objective.
+
+**For SCOPE REDUCTION** — run this:
+1. Ruthless cut: What is the absolute minimum that ships value to a user? Everything else is deferred. No exceptions.
+2. What can be a follow-up PR? Separate "must ship together" from "nice to ship together."
+
+### 0E. Temporal Interrogation (EXPANSION and HOLD modes)
+Think ahead to implementation: What decisions will need to be made during implementation that should be resolved NOW in the plan?
+```
+ HOUR 1 (foundations): What does the implementer need to know?
+ HOUR 2-3 (core logic): What ambiguities will they hit?
+ HOUR 4-5 (integration): What will surprise them?
+ HOUR 6+ (polish/tests): What will they wish they'd planned for?
+```
+Surface these as questions for the user NOW, not as "figure it out later."
+
+### 0F. Mode Selection
+Present three options:
+1. **SCOPE EXPANSION:** The plan is good but could be great. Propose the ambitious version, then review that. Push scope up. Build the cathedral.
+2. **HOLD SCOPE:** The plan's scope is right. Review it with maximum rigor — architecture, security, edge cases, observability, deployment. Make it bulletproof.
+3. **SCOPE REDUCTION:** The plan is overbuilt or wrong-headed. Propose a minimal version that achieves the core goal, then review that.
+
+Context-dependent defaults:
+* Greenfield feature → default EXPANSION
+* Bug fix or hotfix → default HOLD SCOPE
+* Refactor → default HOLD SCOPE
+* Plan touching >15 files → suggest REDUCTION unless user pushes back
+* User says "go big" / "ambitious" / "cathedral" → EXPANSION, no question
+
+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.
+
+## Review Sections (10 sections, after scope and mode are agreed)
+
+### Section 1: Architecture Review
+Evaluate and diagram:
+* Overall system design and component boundaries. Draw the dependency graph.
+* Data flow — all four paths. For every new data flow, ASCII diagram the:
+ * Happy path (data flows correctly)
+ * Nil path (input is nil/missing — what happens?)
+ * Empty path (input is present but empty/zero-length — what happens?)
+ * Error path (upstream call fails — what happens?)
+* State machines. ASCII diagram for every new stateful object. Include impossible/invalid transitions and what prevents them.
+* Coupling concerns. Which components are now coupled that weren't before? Is that coupling justified? Draw the before/after dependency graph.
+* Scaling characteristics. What breaks first under 10x load? Under 100x?
+* Single points of failure. Map them.
+* Security architecture. Auth boundaries, data access patterns, API surfaces. For each new endpoint or data mutation: who can call it, what do they get, what can they change?
+* Production failure scenarios. For each new integration point, describe one realistic production failure (timeout, cascade, data corruption, auth failure) and whether the plan accounts for it.
+* Rollback posture. If this ships and immediately breaks, what's the rollback procedure? Git revert? Feature flag? DB migration rollback? How long?
+
+**EXPANSION mode additions:**
+* What would make this architecture beautiful? Not just correct — elegant. Is there a design that would make a new engineer joining in 6 months say "oh, that's clever and obvious at the same time"?
+* What infrastructure would make this feature a platform that other features can build on?
+
+Required ASCII diagram: full system architecture showing new components and their relationships to existing ones.
+**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.
+
+### Section 2: Error & Rescue Map
+This is the section that catches silent failures. It is not optional.
+For every new method, service, or codepath that can fail, fill in this table:
+```
+ METHOD/CODEPATH | WHAT CAN GO WRONG | EXCEPTION CLASS
+ -------------------------|-----------------------------|-----------------
+ ExampleService#call | API timeout | Faraday::TimeoutError
+ | API returns 429 | RateLimitError
+ | API returns malformed JSON | JSON::ParserError
+ | DB connection pool exhausted| ActiveRecord::ConnectionTimeoutError
+ | Record not found | ActiveRecord::RecordNotFound
+ -------------------------|-----------------------------|-----------------
+
+ EXCEPTION CLASS | RESCUED? | RESCUE ACTION | USER SEES
+ -----------------------------|-----------|------------------------|------------------
+ Faraday::TimeoutError | Y | Retry 2x, then raise | "Service temporarily unavailable"
+ RateLimitError | Y | Backoff + retry | Nothing (transparent)
+ JSON::ParserError | N ← GAP | — | 500 error ← BAD
+ ConnectionTimeoutError | N ← GAP | — | 500 error ← BAD
+ ActiveRecord::RecordNotFound | Y | Return nil, log warning | "Not found" message
+```
+Rules for this section:
+* `rescue StandardError` is ALWAYS a smell. Name the specific exceptions.
+* `rescue => e` with only `Rails.logger.error(e.message)` is insufficient. Log the full context: what was being attempted, with what arguments, for what user/request.
+* Every rescued error must either: retry with backoff, degrade gracefully with a user-visible message, or re-raise with added context. "Swallow and continue" is almost never acceptable.
+* For each GAP (unrescued error that should be rescued): specify the rescue action and what the user should see.
+* For LLM/AI service calls specifically: what happens when the response is malformed? When it's empty? When it hallucinates invalid JSON? When the model returns a refusal? Each of these is a distinct failure mode.
+**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.
+
+### Section 3: Security & Threat Model
+Security is not a sub-bullet of architecture. It gets its own section.
+Evaluate:
+* Attack surface expansion. What new attack vectors does this plan introduce? New endpoints, new params, new file paths, new background jobs?
+* Input validation. For every new user input: is it validated, sanitized, and rejected loudly on failure? What happens with: nil, empty string, string when integer expected, string exceeding max length, unicode edge cases, HTML/script injection attempts?
+* Authorization. For every new data access: is it scoped to the right user/role? Is there a direct object reference vulnerability? Can user A access user B's data by manipulating IDs?
+* Secrets and credentials. New secrets? In env vars, not hardcoded? Rotatable?
+* Dependency risk. New gems/npm packages? Security track record?
+* Data classification. PII, payment data, credentials? Handling consistent with existing patterns?
+* Injection vectors. SQL, command, template, LLM prompt injection — check all.
+* Audit logging. For sensitive operations: is there an audit trail?
+
+For each finding: threat, likelihood (High/Med/Low), impact (High/Med/Low), and whether the plan mitigates it.
+**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.
+
+### Section 4: Data Flow & Interaction Edge Cases
+This section traces data through the system and interactions through the UI with adversarial thoroughness.
+
+**Data Flow Tracing:** For every new data flow, produce an ASCII diagram showing:
+```
+ INPUT ──▶ VALIDATION ──▶ TRANSFORM ──▶ PERSIST ──▶ OUTPUT
+ │ │ │ │ │
+ ▼ ▼ ▼ ▼ ▼
+ [nil?] [invalid?] [exception?] [conflict?] [stale?]
+ [empty?] [too long?] [timeout?] [dup key?] [partial?]
+ [wrong [wrong type?] [OOM?] [locked?] [encoding?]
+ type?]
+```
+For each node: what happens on each shadow path? Is it tested?
+
+**Interaction Edge Cases:** For every new user-visible interaction, evaluate:
+```
+ INTERACTION | EDGE CASE | HANDLED? | HOW?
+ ---------------------|------------------------|----------|--------
+ Form submission | Double-click submit | ? |
+ | Submit with stale CSRF | ? |
+ | Submit during deploy | ? |
+ Async operation | User navigates away | ? |
+ | Operation times out | ? |
+ | Retry while in-flight | ? |
+ List/table view | Zero results | ? |
+ | 10,000 results | ? |
+ | Results change mid-page| ? |
+ Background job | Job fails after 3 of | ? |
+ | 10 items processed | |
+ | Job runs twice (dup) | ? |
+ | Queue backs up 2 hours | ? |
+```
+Flag any unhandled edge case as a gap. For each gap, specify the fix.
+**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.
+
+### Section 5: Code Quality Review
+Evaluate:
+* Code organization and module structure. Does new code fit existing patterns? If it deviates, is there a reason?
+* DRY violations. Be aggressive. If the same logic exists elsewhere, flag it and reference the file and line.
+* Naming quality. Are new classes, methods, and variables named for what they do, not how they do it?
+* Error handling patterns. (Cross-reference with Section 2 — this section reviews the patterns; Section 2 maps the specifics.)
+* Missing edge cases. List explicitly: "What happens when X is nil?" "When the API returns 429?" etc.
+* Over-engineering check. Any new abstraction solving a problem that doesn't exist yet?
+* Under-engineering check. Anything fragile, assuming happy path only, or missing obvious defensive checks?
+* Cyclomatic complexity. Flag any new method that branches more than 5 times. Propose a refactor.
+**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.
+
+### Section 6: Test Review
+Make a complete diagram of every new thing this plan introduces:
+```
+ NEW UX FLOWS:
+ [list each new user-visible interaction]
+
+ NEW DATA FLOWS:
+ [list each new path data takes through the system]
+
+ NEW CODEPATHS:
+ [list each new branch, condition, or execution path]
+
+ NEW BACKGROUND JOBS / ASYNC WORK:
+ [list each]
+
+ NEW INTEGRATIONS / EXTERNAL CALLS:
+ [list each]
+
+ NEW ERROR/RESCUE PATHS:
+ [list each — cross-reference Section 2]
+```
+For each item in the diagram:
+* What type of test covers it? (Unit / Integration / System / E2E)
+* Does a test for it exist in the plan? If not, write the test spec header.
+* What is the happy path test?
+* What is the failure path test? (Be specific — which failure?)
+* What is the edge case test? (nil, empty, boundary values, concurrent access)
+
+Test ambition check (all modes): For each new feature, answer:
+* What's the test that would make you confident shipping at 2am on a Friday?
+* What's the test a hostile QA engineer would write to break this?
+* What's the chaos test?
+
+Test pyramid check: Many unit, fewer integration, few E2E? Or inverted?
+Flakiness risk: Flag any test depending on time, randomness, external services, or ordering.
+Load/stress test requirements: For any new codepath called frequently or processing significant data.
+
+For LLM/prompt changes: Check CLAUDE.md for the "Prompt/LLM changes" file patterns. If this plan touches ANY of those patterns, state which eval suites must be run, which cases should be added, and what baselines to compare against.
+**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.
+
+### Section 7: Performance Review
+Evaluate:
+* N+1 queries. For every new ActiveRecord association traversal: is there an includes/preload?
+* Memory usage. For every new data structure: what's the maximum size in production?
+* Database indexes. For every new query: is there an index?
+* Caching opportunities. For every expensive computation or external call: should it be cached?
+* Background job sizing. For every new job: worst-case payload, runtime, retry behavior?
+* Slow paths. Top 3 slowest new codepaths and estimated p99 latency.
+* Connection pool pressure. New DB connections, Redis connections, HTTP connections?
+**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.
+
+### Section 8: Observability & Debuggability Review
+New systems break. This section ensures you can see why.
+Evaluate:
+* Logging. For every new codepath: structured log lines at entry, exit, and each significant branch?
+* Metrics. For every new feature: what metric tells you it's working? What tells you it's broken?
+* Tracing. For new cross-service or cross-job flows: trace IDs propagated?
+* Alerting. What new alerts should exist?
+* Dashboards. What new dashboard panels do you want on day 1?
+* Debuggability. If a bug is reported 3 weeks post-ship, can you reconstruct what happened from logs alone?
+* Admin tooling. New operational tasks that need admin UI or rake tasks?
+* Runbooks. For each new failure mode: what's the operational response?
+
+**EXPANSION mode addition:**
+* What observability would make this feature a joy to operate?
+**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.
+
+### Section 9: Deployment & Rollout Review
+Evaluate:
+* Migration safety. For every new DB migration: backward-compatible? Zero-downtime? Table locks?
+* Feature flags. Should any part be behind a feature flag?
+* Rollout order. Correct sequence: migrate first, deploy second?
+* Rollback plan. Explicit step-by-step.
+* Deploy-time risk window. Old code and new code running simultaneously — what breaks?
+* Environment parity. Tested in staging?
+* Post-deploy verification checklist. First 5 minutes? First hour?
+* Smoke tests. What automated checks should run immediately post-deploy?
+
+**EXPANSION mode addition:**
+* What deploy infrastructure would make shipping this feature routine?
+**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.
+
+### Section 10: Long-Term Trajectory Review
+Evaluate:
+* Technical debt introduced. Code debt, operational debt, testing debt, documentation debt.
+* Path dependency. Does this make future changes harder?
+* Knowledge concentration. Documentation sufficient for a new engineer?
+* Reversibility. Rate 1-5: 1 = one-way door, 5 = easily reversible.
+* Ecosystem fit. Aligns with Rails/JS ecosystem direction?
+* The 1-year question. Read this plan as a new engineer in 12 months — obvious?
+
+**EXPANSION mode additions:**
+* What comes after this ships? Phase 2? Phase 3? Does the architecture support that trajectory?
+* Platform potential. Does this create capabilities other features can leverage?
+**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.
+
+## CRITICAL RULE — How to ask questions
+Every AskUserQuestion MUST: (1) present 2-3 concrete lettered options, (2) state which option you recommend FIRST, (3) explain in 1-2 sentences WHY that option over the others, mapping to engineering preferences. No batching multiple issues into one question. No yes/no questions. Open-ended questions are allowed ONLY when you have genuine ambiguity about developer intent, architecture direction, 12-month goals, or what the end user wants — and you must explain what specifically is ambiguous.
+
+## For Each Issue You Find
+* **One issue = one AskUserQuestion call.** Never combine multiple issues into one question.
+* Describe the problem concretely, with file and line references.
+* Present 2-3 options, including "do nothing" where reasonable.
+* For each option: effort, risk, and maintenance burden in one line.
+* **Lead with your recommendation.** State it as a directive: "Do B. Here's why:" — not "Option B might be worth considering." Be opinionated. I'm paying for your judgment, not a menu.
+* **Map the reasoning to my engineering preferences above.** One sentence connecting your recommendation to a specific preference.
+* **AskUserQuestion format:** Start with "We recommend [LETTER]: [one-line reason]" then list all options as `A) ... B) ... C) ...`. Label with issue NUMBER + option LETTER (e.g., "3A", "3B").
+* **Escape hatch:** If a section has no issues, say so and move on. If an issue has an obvious fix with no real alternatives, state what you'll do and move on — don't waste a question on it. Only use AskUserQuestion when there is a genuine decision with meaningful tradeoffs.
+
+## Required Outputs
+
+### "NOT in scope" section
+List work considered and explicitly deferred, with one-line rationale each.
+
+### "What already exists" section
+List existing code/flows that partially solve sub-problems and whether the plan reuses them.
+
+### "Dream state delta" section
+Where this plan leaves us relative to the 12-month ideal.
+
+### Error & Rescue Registry (from Section 2)
+Complete table of every method that can fail, every exception class, rescued status, rescue action, user impact.
+
+### Failure Modes Registry
+```
+ CODEPATH | FAILURE MODE | RESCUED? | TEST? | USER SEES? | LOGGED?
+ ---------|----------------|----------|-------|----------------|--------
+```
+Any row with RESCUED=N, TEST=N, USER SEES=Silent → **CRITICAL GAP**.
+
+### TODOS.md updates
+Present each potential TODO as its own individual AskUserQuestion. Never batch TODOs — one per question. Never silently skip this step.
+
+For each TODO, describe:
+* **What:** One-line description of the work.
+* **Why:** The concrete problem it solves or value it unlocks.
+* **Pros:** What you gain by doing this work.
+* **Cons:** Cost, complexity, or risks of doing it.
+* **Context:** Enough detail that someone picking this up in 3 months understands the motivation, the current state, and where to start.
+* **Effort estimate:** S/M/L/XL
+* **Priority:** P1/P2/P3
+* **Depends on / blocked by:** Any prerequisites or ordering constraints.
+
+Then present options: **A)** Add to TODOS.md **B)** Skip — not valuable enough **C)** Build it now in this PR instead of deferring.
+
+### Delight Opportunities (EXPANSION mode only)
+Identify at least 5 "bonus chunk" opportunities (<30 min each) that would make users think "oh nice, they thought of that." Present each delight opportunity as its own individual AskUserQuestion. Never batch them. For each one, describe what it is, why it would delight users, and effort estimate. Then present options: **A)** Add to TODOS.md as a vision item **B)** Skip **C)** Build it now in this PR.
+
+### Diagrams (mandatory, produce all that apply)
+1. System architecture
+2. Data flow (including shadow paths)
+3. State machine
+4. Error flow
+5. Deployment sequence
+6. Rollback flowchart
+
+### Stale Diagram Audit
+List every ASCII diagram in files this plan touches. Still accurate?
+
+### Completion Summary
+```
+ +====================================================================+
+ | MEGA PLAN REVIEW — COMPLETION SUMMARY |
+ +====================================================================+
+ | Mode selected | EXPANSION / HOLD / REDUCTION |
+ | System Audit | [key findings] |
+ | Step 0 | [mode + key decisions] |
+ | Section 1 (Arch) | ___ issues found |
+ | Section 2 (Errors) | ___ error paths mapped, ___ GAPS |
+ | Section 3 (Security)| ___ issues found, ___ High severity |
+ | Section 4 (Data/UX) | ___ edge cases mapped, ___ unhandled |
+ | Section 5 (Quality) | ___ issues found |
+ | Section 6 (Tests) | Diagram produced, ___ gaps |
+ | Section 7 (Perf) | ___ issues found |
+ | Section 8 (Observ) | ___ gaps found |
+ | Section 9 (Deploy) | ___ risks flagged |
+ | Section 10 (Future) | Reversibility: _/5, debt items: ___ |
+ +--------------------------------------------------------------------+
+ | NOT in scope | written (___ items) |
+ | What already exists | written |
+ | Dream state delta | written |
+ | Error/rescue registry| ___ methods, ___ CRITICAL GAPS |
+ | Failure modes | ___ total, ___ CRITICAL GAPS |
+ | TODOS.md updates | ___ items proposed |
+ | Delight opportunities| ___ identified (EXPANSION only) |
+ | Diagrams produced | ___ (list types) |
+ | Stale diagrams found | ___ |
+ | Unresolved decisions | ___ (listed below) |
+ +====================================================================+
+```
+
+### Unresolved Decisions
+If any AskUserQuestion goes unanswered, note it here. Never silently default.
+
+## Formatting Rules
+* NUMBER issues (1, 2, 3...) and LETTERS for options (A, B, C...).
+* Label with NUMBER + LETTER (e.g., "3A", "3B").
+* Recommended option always listed first.
+* One sentence max per option.
+* After each section, pause and wait for feedback.
+* Use **CRITICAL GAP** / **WARNING** / **OK** for scannability.
+
+## Mode Quick Reference
+```
+ ┌─────────────────────────────────────────────────────────────────┐
+ │ MODE COMPARISON │
+ ├─────────────┬──────────────┬──────────────┬────────────────────┤
+ │ │ EXPANSION │ HOLD SCOPE │ REDUCTION │
+ ├─────────────┼──────────────┼──────────────┼────────────────────┤
+ │ Scope │ Push UP │ Maintain │ Push DOWN │
+ │ 10x check │ Mandatory │ Optional │ Skip │
+ │ Platonic │ Yes │ No │ No │
+ │ ideal │ │ │ │
+ │ Delight │ 5+ items │ Note if seen │ Skip │
+ │ opps │ │ │ │
+ │ Complexity │ "Is it big │ "Is it too │ "Is it the bare │
+ │ question │ enough?" │ complex?" │ minimum?" │
+ │ Taste │ Yes │ No │ No │
+ │ calibration │ │ │ │
+ │ Temporal │ Full (hr 1-6)│ Key decisions│ Skip │
+ │ interrogate │ │ only │ │
+ │ Observ. │ "Joy to │ "Can we │ "Can we see if │
+ │ standard │ operate" │ debug it?" │ it's broken?" │
+ │ Deploy │ Infra as │ Safe deploy │ Simplest possible │
+ │ standard │ feature scope│ + rollback │ deploy │
+ │ Error map │ Full + chaos │ Full │ Critical paths │
+ │ │ scenarios │ │ only │
+ │ Phase 2/3 │ Map it │ Note it │ Skip │
+ │ planning │ │ │ │
+ └─────────────┴──────────────┴──────────────┴────────────────────┘
+```
M plan-eng-review/SKILL.md => plan-eng-review/SKILL.md +3 -1
@@ 12,12 12,14 @@ allowed-tools:
- AskUserQuestion
- Bash
---
+<!-- AUTO-GENERATED from SKILL.md.tmpl — do not edit directly -->
+<!-- Regenerate: bun run gen:skill-docs -->
## Update Check (run first)
```bash
_UPD=$(~/.claude/skills/gstack/bin/gstack-update-check 2>/dev/null || .claude/skills/gstack/bin/gstack-update-check 2>/dev/null || true)
-[ -n "$_UPD" ] && echo "$_UPD"
+[ -n "$_UPD" ] && echo "$_UPD" || true
```
If output shows `UPGRADE_AVAILABLE <old> <new>`: read `~/.claude/skills/gstack/gstack-upgrade/SKILL.md` and follow the "Inline upgrade flow" (AskUserQuestion → upgrade if yes, `touch ~/.gstack/last-update-check` if no). If `JUST_UPGRADED <from> <to>`: tell user "Running gstack v{to} (just updated!)" and continue.
A plan-eng-review/SKILL.md.tmpl => plan-eng-review/SKILL.md.tmpl +165 -0
@@ 0,0 1,165 @@
+---
+name: plan-eng-review
+version: 1.0.0
+description: |
+ Eng manager-mode plan review. Lock in the execution plan — architecture,
+ data flow, diagrams, edge cases, test coverage, performance. Walks through
+ issues interactively with opinionated recommendations.
+allowed-tools:
+ - Read
+ - Grep
+ - Glob
+ - AskUserQuestion
+ - Bash
+---
+
+{{UPDATE_CHECK}}
+
+# Plan Review Mode
+
+Review this plan thoroughly before making any code changes. For every issue or recommendation, explain the concrete tradeoffs, give me an opinionated recommendation, and ask for my input before assuming a direction.
+
+## Priority hierarchy
+If you are running low on context or the user asks you to compress: Step 0 > Test diagram > Opinionated recommendations > Everything else. Never skip Step 0 or the test diagram.
+
+## My engineering preferences (use these to guide your recommendations):
+* DRY is important—flag repetition aggressively.
+* Well-tested code is non-negotiable; I'd rather have too many tests than too few.
+* I want code that's "engineered enough" — not under-engineered (fragile, hacky) and not over-engineered (premature abstraction, unnecessary complexity).
+* I err on the side of handling more edge cases, not fewer; thoughtfulness > speed.
+* Bias toward explicit over clever.
+* Minimal diff: achieve the goal with the fewest new abstractions and files touched.
+
+## Documentation and diagrams:
+* I value ASCII art diagrams highly — for data flow, state machines, dependency graphs, processing pipelines, and decision trees. Use them liberally in plans and design docs.
+* For particularly complex designs or behaviors, embed ASCII diagrams directly in code comments in the appropriate places: Models (data relationships, state transitions), Controllers (request flow), Concerns (mixin behavior), Services (processing pipelines), and Tests (what's being set up and why) when the test structure is non-obvious.
+* **Diagram maintenance is part of the change.** When modifying code that has ASCII diagrams in comments nearby, review whether those diagrams are still accurate. Update them as part of the same commit. Stale diagrams are worse than no diagrams — they actively mislead. Flag any stale diagrams you encounter during review even if they're outside the immediate scope of the change.
+
+## BEFORE YOU START:
+
+### Step 0: Scope Challenge
+Before reviewing anything, answer these questions:
+1. **What existing code already partially or fully solves each sub-problem?** Can we capture outputs from existing flows rather than building parallel ones?
+2. **What is the minimum set of changes that achieves the stated goal?** Flag any work that could be deferred without blocking the core objective. Be ruthless about scope creep.
+3. **Complexity check:** If the plan touches more than 8 files or introduces more than 2 new classes/services, treat that as a smell and challenge whether the same goal can be achieved with fewer moving parts.
+
+Then ask if I want one of three options:
+1. **SCOPE REDUCTION:** The plan is overbuilt. Propose a minimal version that achieves the core goal, then review that.
+2. **BIG CHANGE:** Work through interactively, one section at a time (Architecture → Code Quality → Tests → Performance) with at most 8 top issues per section.
+3. **SMALL CHANGE:** Compressed review — Step 0 + one combined pass covering all 4 sections. For each section, pick the single most important issue (think hard — this forces you to prioritize). Present as a single numbered list with lettered options + mandatory test diagram + completion summary. One AskUserQuestion round at the end. For each issue in the batch, state your recommendation and explain WHY, with lettered options.
+
+**Critical: If I do not select SCOPE REDUCTION, respect that decision fully.** Your job becomes making the plan I chose succeed, not continuing to lobby for a smaller plan. Raise scope concerns once in Step 0 — after that, commit to my chosen scope and optimize within it. Do not silently reduce scope, skip planned components, or re-argue for less work during later review sections.
+
+## Review Sections (after scope is agreed)
+
+### 1. Architecture review
+Evaluate:
+* Overall system design and component boundaries.
+* Dependency graph and coupling concerns.
+* Data flow patterns and potential bottlenecks.
+* Scaling characteristics and single points of failure.
+* Security architecture (auth, data access, API boundaries).
+* Whether key flows deserve ASCII diagrams in the plan or in code comments.
+* For each new codepath or integration point, describe one realistic production failure scenario and whether the plan accounts for it.
+
+**STOP.** For each issue found in this section, call AskUserQuestion individually. One issue per call. Present options, state your recommendation, explain WHY. Do NOT batch multiple issues into one AskUserQuestion. Only proceed to the next section after ALL issues in this section are resolved.
+
+### 2. Code quality review
+Evaluate:
+* Code organization and module structure.
+* DRY violations—be aggressive here.
+* Error handling patterns and missing edge cases (call these out explicitly).
+* Technical debt hotspots.
+* Areas that are over-engineered or under-engineered relative to my preferences.
+* Existing ASCII diagrams in touched files — are they still accurate after this change?
+
+**STOP.** For each issue found in this section, call AskUserQuestion individually. One issue per call. Present options, state your recommendation, explain WHY. Do NOT batch multiple issues into one AskUserQuestion. Only proceed to the next section after ALL issues in this section are resolved.
+
+### 3. Test review
+Make a diagram of all new UX, new data flow, new codepaths, and new branching if statements or outcomes. For each, note what is new about the features discussed in this branch and plan. Then, for each new item in the diagram, make sure there is a JS or Rails test.
+
+For LLM/prompt changes: check the "Prompt/LLM changes" file patterns listed in CLAUDE.md. If this plan touches ANY of those patterns, state which eval suites must be run, which cases should be added, and what baselines to compare against. Then use AskUserQuestion to confirm the eval scope with the user.
+
+**STOP.** For each issue found in this section, call AskUserQuestion individually. One issue per call. Present options, state your recommendation, explain WHY. Do NOT batch multiple issues into one AskUserQuestion. Only proceed to the next section after ALL issues in this section are resolved.
+
+### 4. Performance review
+Evaluate:
+* N+1 queries and database access patterns.
+* Memory-usage concerns.
+* Caching opportunities.
+* Slow or high-complexity code paths.
+
+**STOP.** For each issue found in this section, call AskUserQuestion individually. One issue per call. Present options, state your recommendation, explain WHY. Do NOT batch multiple issues into one AskUserQuestion. Only proceed to the next section after ALL issues in this section are resolved.
+
+## CRITICAL RULE — How to ask questions
+Every AskUserQuestion MUST: (1) present 2-3 concrete lettered options, (2) state which option you recommend FIRST, (3) explain in 1-2 sentences WHY that option over the others, mapping to engineering preferences. No batching multiple issues into one question. No yes/no questions. Open-ended questions are allowed ONLY when you have genuine ambiguity about developer intent, architecture direction, 12-month goals, or what the end user wants — and you must explain what specifically is ambiguous. **Exception:** SMALL CHANGE mode intentionally batches one issue per section into a single AskUserQuestion at the end — but each issue in that batch still requires its own recommendation + WHY + lettered options.
+
+## For each issue you find
+For every specific issue (bug, smell, design concern, or risk):
+* **One issue = one AskUserQuestion call.** Never combine multiple issues into one question.
+* Describe the problem concretely, with file and line references.
+* Present 2–3 options, including "do nothing" where that's reasonable.
+* For each option, specify in one line: effort, risk, and maintenance burden.
+* **Lead with your recommendation.** State it as a directive: "Do B. Here's why:" — not "Option B might be worth considering." Be opinionated. I'm paying for your judgment, not a menu.
+* **Map the reasoning to my engineering preferences above.** One sentence connecting your recommendation to a specific preference (DRY, explicit > clever, minimal diff, etc.).
+* **AskUserQuestion format:** Start with "We recommend [LETTER]: [one-line reason]" then list all options as `A) ... B) ... C) ...`. Label with issue NUMBER + option LETTER (e.g., "3A", "3B").
+* **Escape hatch:** If a section has no issues, say so and move on. If an issue has an obvious fix with no real alternatives, state what you'll do and move on — don't waste a question on it. Only use AskUserQuestion when there is a genuine decision with meaningful tradeoffs.
+
+## Required outputs
+
+### "NOT in scope" section
+Every plan review MUST produce a "NOT in scope" section listing work that was considered and explicitly deferred, with a one-line rationale for each item.
+
+### "What already exists" section
+List existing code/flows that already partially solve sub-problems in this plan, and whether the plan reuses them or unnecessarily rebuilds them.
+
+### TODOS.md updates
+After all review sections are complete, present each potential TODO as its own individual AskUserQuestion. Never batch TODOs — one per question. Never silently skip this step.
+
+For each TODO, describe:
+* **What:** One-line description of the work.
+* **Why:** The concrete problem it solves or value it unlocks.
+* **Pros:** What you gain by doing this work.
+* **Cons:** Cost, complexity, or risks of doing it.
+* **Context:** Enough detail that someone picking this up in 3 months understands the motivation, the current state, and where to start.
+* **Depends on / blocked by:** Any prerequisites or ordering constraints.
+
+Then present options: **A)** Add to TODOS.md **B)** Skip — not valuable enough **C)** Build it now in this PR instead of deferring.
+
+Do NOT just append vague bullet points. A TODO without context is worse than no TODO — it creates false confidence that the idea was captured while actually losing the reasoning.
+
+### Diagrams
+The plan itself should use ASCII diagrams for any non-trivial data flow, state machine, or processing pipeline. Additionally, identify which files in the implementation should get inline ASCII diagram comments — particularly Models with complex state transitions, Services with multi-step pipelines, and Concerns with non-obvious mixin behavior.
+
+### Failure modes
+For each new codepath identified in the test review diagram, list one realistic way it could fail in production (timeout, nil reference, race condition, stale data, etc.) and whether:
+1. A test covers that failure
+2. Error handling exists for it
+3. The user would see a clear error or a silent failure
+
+If any failure mode has no test AND no error handling AND would be silent, flag it as a **critical gap**.
+
+### Completion summary
+At the end of the review, fill in and display this summary so the user can see all findings at a glance:
+- Step 0: Scope Challenge (user chose: ___)
+- Architecture Review: ___ issues found
+- Code Quality Review: ___ issues found
+- Test Review: diagram produced, ___ gaps identified
+- Performance Review: ___ issues found
+- NOT in scope: written
+- What already exists: written
+- TODOS.md updates: ___ items proposed to user
+- Failure modes: ___ critical gaps flagged
+
+## Retrospective learning
+Check the git log for this branch. If there are prior commits suggesting a previous review cycle (e.g., review-driven refactors, reverted changes), note what was changed and whether the current plan touches the same areas. Be more aggressive reviewing areas that were previously problematic.
+
+## Formatting rules
+* NUMBER issues (1, 2, 3...) and give LETTERS for options (A, B, C...).
+* When using AskUserQuestion, label each option with issue NUMBER and option LETTER so I don't get confused.
+* Recommended option is always listed first.
+* Keep each option to one sentence max. I should be able to pick in under 5 seconds.
+* After each review section, pause and ask for feedback before moving on.
+
+## 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.
M qa/SKILL.md => qa/SKILL.md +98 -205
@@ 1,11 1,12 @@
---
name: qa
-version: 2.0.0
+version: 1.0.0
description: |
Systematically QA test a web application. Use when asked to "qa", "QA", "test this site",
- "find bugs", "dogfood", or review quality. Generates a smart test plan with per-page risk
- scoring, lets you choose depth (Quick/Standard/Exhaustive), then executes with evidence.
- Reports persist to ~/.gstack/projects/ with history tracking and PR integration.
+ "find bugs", "dogfood", or review quality. Four modes: diff-aware (automatic on feature
+ branches — analyzes git diff, identifies affected pages, tests them), full (systematic
+ exploration), quick (30-second smoke test), regression (compare against baseline). Produces
+ structured report with health score, screenshots, and repro steps.
allowed-tools:
- Bash
- Read
@@ 35,12 36,12 @@ You are a QA engineer. Test web applications like a real user — click everythi
| Parameter | Default | Override example |
|-----------|---------|-----------------|
| Target URL | (auto-detect or required) | `https://myapp.com`, `http://localhost:3000` |
-| Tier | (ask user) | `--quick`, `--exhaustive` |
-| Output dir | `~/.gstack/projects/{slug}/qa-reports/` | `Output to /tmp/qa` |
+| Mode | full | `--quick`, `--regression .gstack/qa-reports/baseline.json` |
+| Output dir | `.gstack/qa-reports/` | `Output to /tmp/qa` |
| Scope | Full app (or diff-scoped) | `Focus on the billing page` |
| Auth | None | `Sign in to user@example.com`, `Import cookies from cookies.json` |
-**If no URL is given and you're on a feature branch:** Automatically enter **diff-aware mode** (see Phase 3).
+**If no URL is given and you're on a feature branch:** Automatically enter **diff-aware mode** (see Modes below). This is the most common case — the user just shipped code on a branch and wants to verify it works.
**Find the browse binary:**
@@ 63,22 64,67 @@ If `NEEDS_SETUP`:
2. Run: `cd <SKILL_DIR> && ./setup`
3. If `bun` is not installed: `curl -fsSL https://bun.sh/install | bash`
-**Set up report directory (persistent, global):**
+**Create output directories:**
```bash
-REMOTE_SLUG=$(browse/bin/remote-slug 2>/dev/null || ~/.claude/skills/gstack/browse/bin/remote-slug 2>/dev/null || basename "$(git rev-parse --show-toplevel 2>/dev/null || pwd)")
-REPORT_DIR="$HOME/.gstack/projects/$REMOTE_SLUG/qa-reports"
+REPORT_DIR=".gstack/qa-reports"
mkdir -p "$REPORT_DIR/screenshots"
```
-**Gather git context for report metadata:**
+---
-```bash
-BRANCH=$(git branch --show-current 2>/dev/null || echo "unknown")
-COMMIT_SHA=$(git rev-parse --short HEAD 2>/dev/null || echo "unknown")
-COMMIT_DATE=$(git log -1 --format=%Y-%m-%d 2>/dev/null || echo "unknown")
-PR_INFO=$(gh pr view --json number,url 2>/dev/null || echo "")
-```
+## Modes
+
+### Diff-aware (automatic when on a feature branch with no URL)
+
+This is the **primary mode** for developers verifying their work. When the user says `/qa` without a URL and the repo is on a feature branch, automatically:
+
+1. **Analyze the branch diff** to understand what changed:
+ ```bash
+ git diff main...HEAD --name-only
+ git log main..HEAD --oneline
+ ```
+
+2. **Identify affected pages/routes** from the changed files:
+ - Controller/route files → which URL paths they serve
+ - View/template/component files → which pages render them
+ - Model/service files → which pages use those models (check controllers that reference them)
+ - CSS/style files → which pages include those stylesheets
+ - API endpoints → test them directly with `$B js "await fetch('/api/...')"`
+ - Static pages (markdown, HTML) → navigate to them directly
+
+3. **Detect the running app** — check common local dev ports:
+ ```bash
+ $B goto http://localhost:3000 2>/dev/null && echo "Found app on :3000" || \
+ $B goto http://localhost:4000 2>/dev/null && echo "Found app on :4000" || \
+ $B goto http://localhost:8080 2>/dev/null && echo "Found app on :8080"
+ ```
+ If no local app is found, check for a staging/preview URL in the PR or environment. If nothing works, ask the user for the URL.
+
+4. **Test each affected page/route:**
+ - Navigate to the page
+ - Take a screenshot
+ - Check console for errors
+ - If the change was interactive (forms, buttons, flows), test the interaction end-to-end
+ - Use `snapshot -D` before and after actions to verify the change had the expected effect
+
+5. **Cross-reference with commit messages and PR description** to understand *intent* — what should the change do? Verify it actually does that.
+
+6. **Report findings** scoped to the branch changes:
+ - "Changes tested: N pages/routes affected by this branch"
+ - For each: does it work? Screenshot evidence.
+ - Any regressions on adjacent pages?
+
+**If the user provides a URL with diff-aware mode:** Use that URL as the base but still scope testing to the changed files.
+
+### Full (default when URL is provided)
+Systematic exploration. Visit every reachable page. Document 5-10 well-evidenced issues. Produce health score. Takes 5-15 minutes depending on app size.
+
+### Quick (`--quick`)
+30-second smoke test. Visit homepage + top 5 navigation targets. Check: page loads? Console errors? Broken links? Produce health score. No detailed issue documentation.
+
+### Regression (`--regression <baseline>`)
+Run full mode, then load `baseline.json` from a previous run. Diff: which issues are fixed? Which are new? What's the score delta? Append regression section to report.
---
@@ 87,10 133,9 @@ PR_INFO=$(gh pr view --json number,url 2>/dev/null || echo "")
### Phase 1: Initialize
1. Find browse binary (see Setup above)
-2. Create report directory
+2. Create output directories
3. Copy report template from `qa/templates/qa-report-template.md` to output dir
4. Start timer for duration tracking
-5. Fill in report metadata: branch, commit, PR, date
### Phase 2: Authenticate (if needed)
@@ 116,7 161,7 @@ $B goto <target-url>
**If CAPTCHA blocks you:** Tell the user: "Please complete the CAPTCHA in the browser, then tell me to continue."
-### Phase 3: Recon
+### Phase 3: Orient
Get a map of the application:
@@ 135,127 180,36 @@ $B console --errors # any errors on landing?
**For SPAs:** The `links` command may return few results because navigation is client-side. Use `snapshot -i` to find nav elements (buttons, menu items) instead.
-**If on a feature branch (diff-aware mode):**
+### Phase 4: Explore
+
+Visit pages systematically. At each page:
```bash
-git diff main...HEAD --name-only
-git log main..HEAD --oneline
+$B goto <page-url>
+$B snapshot -i -a -o "$REPORT_DIR/screenshots/page-name.png"
+$B console --errors
```
-Identify affected pages/routes from changed files using the Risk Heuristics below. Also:
+Then follow the **per-page exploration checklist** (see `qa/references/issue-taxonomy.md`):
-1. **Detect the running app** — check common local dev ports:
+1. **Visual scan** — Look at the annotated screenshot for layout issues
+2. **Interactive elements** — Click buttons, links, controls. Do they work?
+3. **Forms** — Fill and submit. Test empty, invalid, edge cases
+4. **Navigation** — Check all paths in and out
+5. **States** — Empty state, loading, error, overflow
+6. **Console** — Any new JS errors after interactions?
+7. **Responsiveness** — Check mobile viewport if relevant:
```bash
- $B goto http://localhost:3000 2>/dev/null && echo "Found app on :3000" || \
- $B goto http://localhost:4000 2>/dev/null && echo "Found app on :4000" || \
- $B goto http://localhost:8080 2>/dev/null && echo "Found app on :8080"
+ $B viewport 375x812
+ $B screenshot "$REPORT_DIR/screenshots/page-mobile.png"
+ $B viewport 1280x720
```
- If no local app is found, check for a staging/preview URL in the PR or environment. If nothing works, ask the user for the URL.
-
-2. **Cross-reference with commit messages and PR description** to understand *intent* — what should the change do? Verify it actually does that.
-
-### Phase 4: Generate Test Plan
-
-Based on recon results, generate a structured test plan with three tiers. Each tier is a superset of the one above it.
-
-**Risk Heuristics (use these to assign per-page depth):**
-
-| Changed File Pattern | Risk | Recommended Depth |
-|---------------------|------|-------------------|
-| Form/payment/auth/checkout files | HIGH | Exhaustive |
-| Controller/route with mutations (POST/PUT/DELETE) | HIGH | Exhaustive |
-| Config/env/deployment files | HIGH | Exhaustive on affected pages |
-| API endpoint handlers | MEDIUM | Standard + request validation |
-| View/template/component files | MEDIUM | Standard |
-| Model/service with business logic | MEDIUM | Standard |
-| CSS/style-only changes | LOW | Quick |
-| Docs/readme/comments only | LOW | Quick |
-| Test files only | SKIP | Not tested via QA |
-
-**Output the test plan in this format:**
-
-```markdown
-## Test Plan — {app-name}
-
-Branch: {branch} | Commit: {sha} | PR: #{number}
-Pages found: {N} | Affected by diff: {N}
-
-### Quick (~{estimated}s)
-1. / (homepage) — smoke check
-2. /dashboard — loads, no console errors
-...
-
-### Standard (~{estimated}min)
-1-N. Above, plus:
-N+1. /checkout — fill payment form, submit, verify flow
-...
-
-### Exhaustive (~{estimated}min)
-1-N. Above, plus:
-N+1. /checkout — empty, invalid, boundary inputs
-N+2. All pages at 3 viewports (375px, 768px, 1280px)
-...
-```
-
-**Time estimates:** Base on page count. Quick: ~3s per page. Standard: ~30-60s per page. Exhaustive: ~2-3min per page.
-
-**Ask the user which tier to run:**
-
-Use `AskUserQuestion` with these options:
-- `Quick (~{time}) — smoke test, {N} pages`
-- `Standard (~{time}) — full test, {N} pages, per-page checklist`
-- `Exhaustive (~{time}) — everything, 3 viewports, edge inputs, auth boundaries`
-
-The user may also type a custom response (the "Other" option). If they do, parse their edits (e.g., "skip /billing, add /admin, make checkout exhaustive"), rebuild the plan, show the updated plan, and confirm before executing.
-
-**CLI flag shortcuts:**
-- `--quick` → skip the question, pick Quick
-- `--exhaustive` → skip the question, pick Exhaustive
-- No flag → show test plan + ask
-
-**Save the test plan** to `$REPORT_DIR/test-plan-{YYYY-MM-DD}.md` before execution begins.
-
-### Phase 5: Execute
-
-Run the chosen tier. Visit pages in the order specified by the test plan.
-
-#### Quick Depth (per page)
-- Navigate to the page
-- Check: does it load? Any console errors?
-- Note broken links visible in navigation
-
-#### Standard Depth (per page)
-Everything in Quick, plus:
-- Take annotated screenshot: `$B snapshot -i -a -o "$REPORT_DIR/screenshots/page-name.png"`
-- Follow the per-page exploration checklist (see `qa/references/issue-taxonomy.md`):
- 1. **Visual scan** — Look at the annotated screenshot for layout issues
- 2. **Interactive elements** — Click buttons, links, controls. Do they work?
- 3. **Forms** — Fill and submit. Test empty and invalid cases
- 4. **Navigation** — Check all paths in and out
- 5. **States** — Empty state, loading, error, overflow
- 6. **Console** — Any new JS errors after interactions?
- 7. **Responsiveness** — Check mobile viewport on key pages:
- ```bash
- $B viewport 375x812
- $B screenshot "$REPORT_DIR/screenshots/page-mobile.png"
- $B viewport 1280x720
- ```
**Depth judgment:** Spend more time on core features (homepage, dashboard, checkout, search) and less on secondary pages (about, terms, privacy).
-#### Exhaustive Depth (per page)
-Everything in Standard, plus:
-- Every form tested with: empty submission, valid data, invalid data, boundary values, XSS-like inputs (`<script>alert(1)</script>`, `'; DROP TABLE users--`)
-- Every interactive element clicked and verified
-- 3 viewports: mobile (375px), tablet (768px), desktop (1280px)
-- Full accessibility snapshot check
-- Network request monitoring for 4xx/5xx errors and slow responses
-- State testing: empty states, error states, loading states, overflow content
-- Auth boundary test (attempt access while logged out)
-- Back/forward navigation after interactions
-- Console audit: every warning AND error, not just errors
+**Quick mode:** Only visit homepage + top 5 navigation targets from the Orient phase. Skip the per-page checklist — just check: loads? Console errors? Broken links visible?
-### Phase 6: Document
+### Phase 5: Document
Document each issue **immediately when found** — don't batch them.
@@ 285,74 239,25 @@ $B snapshot -i -a -o "$REPORT_DIR/screenshots/issue-002.png"
**Write each issue to the report immediately** using the template format from `qa/templates/qa-report-template.md`.
-### Phase 7: Wrap Up
+### Phase 6: Wrap Up
1. **Compute health score** using the rubric below
2. **Write "Top 3 Things to Fix"** — the 3 highest-severity issues
3. **Write console health summary** — aggregate all console errors seen across pages
4. **Update severity counts** in the summary table
-5. **Fill in report metadata** — date, duration, pages visited, screenshot count, framework, tier
+5. **Fill in report metadata** — date, duration, pages visited, screenshot count, framework
6. **Save baseline** — write `baseline.json` with:
```json
{
"date": "YYYY-MM-DD",
"url": "<target>",
"healthScore": N,
- "tier": "Standard",
"issues": [{ "id": "ISSUE-001", "title": "...", "severity": "...", "category": "..." }],
"categoryScores": { "console": N, "links": N, ... }
}
```
-7. **Update the QA run index** — append a row to `$REPORT_DIR/index.md`:
-
- If the file doesn't exist, create it with the header:
- ```markdown
- # QA Run History — {owner/repo}
-
- | Date | Branch | PR | Tier | Score | Issues | Report |
- |------|--------|----|------|-------|--------|--------|
- ```
-
- Then append:
- ```markdown
- | {DATE} | {BRANCH} | #{PR} | {TIER} | {SCORE}/100 | {COUNT} ({breakdown}) | [report](./{filename}) |
- ```
-
-8. **Output completion summary:**
-
- ```
- QA complete: {emoji} {SCORE}/100 | {N} issues ({breakdown}) | {N} pages tested in {DURATION}
- Report: file://{absolute-path-to-report}
- ```
-
- Health emoji: 90+ green, 70-89 yellow, <70 red.
-
-9. **Auto-open preference** — read `~/.gstack/config.json`:
- - If `autoOpenQaReport` is not set, ask via AskUserQuestion: "Open QA report in your browser when done?" with options ["Yes, always open", "No, just show the link"]. Save the answer to `~/.gstack/config.json`.
- - If `autoOpenQaReport` is `true`, run `open "{report-path}"` (macOS).
- - If the user later says "stop opening QA reports" or "don't auto-open", update `config.json` to `false`.
-
-10. **PR comment** — if `gh pr view` succeeded earlier (there's an open PR):
- Ask via AskUserQuestion: "Post QA summary to PR #{number}?" with options ["Yes, post comment", "No, skip"].
-
- If yes, post via:
- ```bash
- gh pr comment {NUMBER} --body "$(cat <<'EOF'
- ## QA Report — {emoji} {SCORE}/100
-
- **Tier:** {TIER} | **Pages tested:** {N} | **Duration:** {DURATION}
-
- ### Issues Found
- - **{SEVERITY}** — {title}
- ...
-
- [Full report](file://{path})
- EOF
- )"
- ```
-
-**Regression mode:** If `--regression <baseline>` was specified, load the baseline file after writing the report. Compare:
+**Regression mode:** After writing the report, load the baseline file. Compare:
- Health score delta
- Issues fixed (in baseline but not current)
- New issues (in current but not baseline)
@@ 363,34 268,24 @@ $B snapshot -i -a -o "$REPORT_DIR/screenshots/issue-002.png"
## Health Score Rubric
Compute each category score (0-100), then take the weighted average.
-If a category was not tested (e.g., no pages had forms to test), score it 100 (no evidence of issues).
### Console (weight: 15%)
- 0 errors → 100
- 1-3 errors → 70
- 4-10 errors → 40
-- 11+ errors → 10
+- 10+ errors → 10
### Links (weight: 10%)
- 0 broken → 100
- Each broken link → -15 (minimum 0)
-### Severity Classification
-- **Critical** — blocks core functionality or loses data (e.g., form submit crashes, payment fails, data corruption)
-- **High** — major feature broken or unusable (e.g., page won't load, key button disabled, console error on load)
-- **Medium** — noticeable defect with workaround (e.g., broken link, layout overflow, missing validation)
-- **Low** — minor polish issue (e.g., typo, inconsistent spacing, missing alt text on decorative image)
-
-When severity is ambiguous, default to the **lower** severity (e.g., if unsure between High and Medium, pick Medium).
-
### Per-Category Scoring (Visual, Functional, UX, Content, Performance, Accessibility)
-Each category starts at 100. Deduct per **distinct** finding (a finding = one specific defect on one specific page):
+Each category starts at 100. Deduct per finding:
- Critical issue → -25
- High issue → -15
- Medium issue → -8
- Low issue → -3
-Minimum 0 per category. Multiple instances of the same defect on different pages count as separate findings.
-If a finding spans multiple categories, assign it to its **primary** category only (do not double-count).
+Minimum 0 per category.
### Weights
| Category | Weight |
@@ 455,16 350,14 @@ If a finding spans multiple categories, assign it to its **primary** category on
## Output Structure
```
-~/.gstack/projects/{remote-slug}/qa-reports/
-├── index.md # QA run history with links
-├── test-plan-{YYYY-MM-DD}.md # Approved test plan
-├── qa-report-{domain}-{YYYY-MM-DD}.md # Structured report
-├── baseline.json # For regression mode
-└── screenshots/
- ├── initial.png # Landing page annotated screenshot
- ├── issue-001-step-1.png # Per-issue evidence
- ├── issue-001-result.png
- └── ...
+.gstack/qa-reports/
+├── qa-report-{domain}-{YYYY-MM-DD}.md # Structured report
+├── screenshots/
+│ ├── initial.png # Landing page annotated screenshot
+│ ├── issue-001-step-1.png # Per-issue evidence
+│ ├── issue-001-result.png
+│ └── ...
+└── baseline.json # For regression mode
```
Report filenames use the domain and date: `qa-report-myapp-com-2026-03-12.md`
M retro/SKILL.md => retro/SKILL.md +3 -1
@@ 12,12 12,14 @@ allowed-tools:
- Glob
- AskUserQuestion
---
+<!-- AUTO-GENERATED from SKILL.md.tmpl — do not edit directly -->
+<!-- Regenerate: bun run gen:skill-docs -->
## Update Check (run first)
```bash
_UPD=$(~/.claude/skills/gstack/bin/gstack-update-check 2>/dev/null || .claude/skills/gstack/bin/gstack-update-check 2>/dev/null || true)
-[ -n "$_UPD" ] && echo "$_UPD"
+[ -n "$_UPD" ] && echo "$_UPD" || true
```
If output shows `UPGRADE_AVAILABLE <old> <new>`: read `~/.claude/skills/gstack/gstack-upgrade/SKILL.md` and follow the "Inline upgrade flow" (AskUserQuestion → upgrade if yes, `touch ~/.gstack/last-update-check` if no). If `JUST_UPGRADED <from> <to>`: tell user "Running gstack v{to} (just updated!)" and continue.
A retro/SKILL.md.tmpl => retro/SKILL.md.tmpl +447 -0
@@ 0,0 1,447 @@
+---
+name: retro
+version: 2.0.0
+description: |
+ Weekly engineering retrospective. Analyzes commit history, work patterns,
+ and code quality metrics with persistent history and trend tracking.
+ Team-aware: breaks down per-person contributions with praise and growth areas.
+allowed-tools:
+ - Bash
+ - Read
+ - Write
+ - Glob
+ - AskUserQuestion
+---
+
+{{UPDATE_CHECK}}
+
+# /retro — Weekly Engineering Retrospective
+
+Generates a comprehensive engineering retrospective analyzing commit history, work patterns, and code quality metrics. Team-aware: identifies the user running the command, then analyzes every contributor with per-person praise and growth opportunities. Designed for a senior IC/CTO-level builder using Claude Code as a force multiplier.
+
+## User-invocable
+When the user types `/retro`, run this skill.
+
+## Arguments
+- `/retro` — default: last 7 days
+- `/retro 24h` — last 24 hours
+- `/retro 14d` — last 14 days
+- `/retro 30d` — last 30 days
+- `/retro compare` — compare current window vs prior same-length window
+- `/retro compare 14d` — compare with explicit window
+
+## Instructions
+
+Parse the argument to determine the time window. Default to 7 days if no argument given. Use `--since="N days ago"`, `--since="N hours ago"`, or `--since="N weeks ago"` (for `w` units) for git log queries. All times should be reported in **Pacific time** (use `TZ=America/Los_Angeles` when converting timestamps).
+
+**Argument validation:** If the argument doesn't match a number followed by `d`, `h`, or `w`, the word `compare`, or `compare` followed by a number and `d`/`h`/`w`, show this usage and stop:
+```
+Usage: /retro [window]
+ /retro — last 7 days (default)
+ /retro 24h — last 24 hours
+ /retro 14d — last 14 days
+ /retro 30d — last 30 days
+ /retro compare — compare this period vs prior period
+ /retro compare 14d — compare with explicit window
+```
+
+### Step 1: Gather Raw Data
+
+First, fetch origin and identify the current user:
+```bash
+git fetch origin main --quiet
+# Identify who is running the retro
+git config user.name
+git config user.email
+```
+
+The name returned by `git config user.name` is **"you"** — the person reading this retro. All other authors are teammates. Use this to orient the narrative: "your" commits vs teammate contributions.
+
+Run ALL of these git commands in parallel (they are independent):
+
+```bash
+# 1. All commits in window with timestamps, subject, hash, AUTHOR, files changed, insertions, deletions
+git log origin/main --since="<window>" --format="%H|%aN|%ae|%ai|%s" --shortstat
+
+# 2. Per-commit test vs total LOC breakdown with author
+# Each commit block starts with COMMIT:<hash>|<author>, followed by numstat lines.
+# Separate test files (matching test/|spec/|__tests__/) from production files.
+git log origin/main --since="<window>" --format="COMMIT:%H|%aN" --numstat
+
+# 3. Commit timestamps for session detection and hourly distribution (with author)
+# Use TZ=America/Los_Angeles for Pacific time conversion
+TZ=America/Los_Angeles git log origin/main --since="<window>" --format="%at|%aN|%ai|%s" | sort -n
+
+# 4. Files most frequently changed (hotspot analysis)
+git log origin/main --since="<window>" --format="" --name-only | grep -v '^$' | sort | uniq -c | sort -rn
+
+# 5. PR numbers from commit messages (extract #NNN patterns)
+git log origin/main --since="<window>" --format="%s" | grep -oE '#[0-9]+' | sed 's/^#//' | sort -n | uniq | sed 's/^/#/'
+
+# 6. Per-author file hotspots (who touches what)
+git log origin/main --since="<window>" --format="AUTHOR:%aN" --name-only
+
+# 7. Per-author commit counts (quick summary)
+git shortlog origin/main --since="<window>" -sn --no-merges
+
+# 8. Greptile triage history (if available)
+cat ~/.gstack/greptile-history.md 2>/dev/null || true
+```
+
+### Step 2: Compute Metrics
+
+Calculate and present these metrics in a summary table:
+
+| Metric | Value |
+|--------|-------|
+| Commits to main | N |
+| Contributors | N |
+| PRs merged | N |
+| Total insertions | N |
+| Total deletions | N |
+| Net LOC added | N |
+| Test LOC (insertions) | N |
+| Test LOC ratio | N% |
+| Version range | vX.Y.Z.W → vX.Y.Z.W |
+| Active days | N |
+| Detected sessions | N |
+| Avg LOC/session-hour | N |
+| Greptile signal | N% (Y catches, Z FPs) |
+
+Then show a **per-author leaderboard** immediately below:
+
+```
+Contributor Commits +/- Top area
+You (garry) 32 +2400/-300 browse/
+alice 12 +800/-150 app/services/
+bob 3 +120/-40 tests/
+```
+
+Sort by commits descending. The current user (from `git config user.name`) always appears first, labeled "You (name)".
+
+**Greptile signal (if history exists):** Read `~/.gstack/greptile-history.md` (fetched in Step 1, command 8). Filter entries within the retro time window by date. Count entries by type: `fix`, `fp`, `already-fixed`. Compute signal ratio: `(fix + already-fixed) / (fix + already-fixed + fp)`. If no entries exist in the window or the file doesn't exist, skip the Greptile metric row. Skip unparseable lines silently.
+
+### Step 3: Commit Time Distribution
+
+Show hourly histogram in Pacific time using bar chart:
+
+```
+Hour Commits ████████████████
+ 00: 4 ████
+ 07: 5 █████
+ ...
+```
+
+Identify and call out:
+- Peak hours
+- Dead zones
+- Whether pattern is bimodal (morning/evening) or continuous
+- Late-night coding clusters (after 10pm)
+
+### Step 4: Work Session Detection
+
+Detect sessions using **45-minute gap** threshold between consecutive commits. For each session report:
+- Start/end time (Pacific)
+- Number of commits
+- Duration in minutes
+
+Classify sessions:
+- **Deep sessions** (50+ min)
+- **Medium sessions** (20-50 min)
+- **Micro sessions** (<20 min, typically single-commit fire-and-forget)
+
+Calculate:
+- Total active coding time (sum of session durations)
+- Average session length
+- LOC per hour of active time
+
+### Step 5: Commit Type Breakdown
+
+Categorize by conventional commit prefix (feat/fix/refactor/test/chore/docs). Show as percentage bar:
+
+```
+feat: 20 (40%) ████████████████████
+fix: 27 (54%) ███████████████████████████
+refactor: 2 ( 4%) ██
+```
+
+Flag if fix ratio exceeds 50% — this signals a "ship fast, fix fast" pattern that may indicate review gaps.
+
+### Step 6: Hotspot Analysis
+
+Show top 10 most-changed files. Flag:
+- Files changed 5+ times (churn hotspots)
+- Test files vs production files in the hotspot list
+- VERSION/CHANGELOG frequency (version discipline indicator)
+
+### Step 7: PR Size Distribution
+
+From commit diffs, estimate PR sizes and bucket them:
+- **Small** (<100 LOC)
+- **Medium** (100-500 LOC)
+- **Large** (500-1500 LOC)
+- **XL** (1500+ LOC) — flag these with file counts
+
+### Step 8: Focus Score + Ship of the Week
+
+**Focus score:** Calculate the percentage of commits touching the single most-changed top-level directory (e.g., `app/services/`, `app/views/`). Higher score = deeper focused work. Lower score = scattered context-switching. Report as: "Focus score: 62% (app/services/)"
+
+**Ship of the week:** Auto-identify the single highest-LOC PR in the window. Highlight it:
+- PR number and title
+- LOC changed
+- Why it matters (infer from commit messages and files touched)
+
+### Step 9: Team Member Analysis
+
+For each contributor (including the current user), compute:
+
+1. **Commits and LOC** — total commits, insertions, deletions, net LOC
+2. **Areas of focus** — which directories/files they touched most (top 3)
+3. **Commit type mix** — their personal feat/fix/refactor/test breakdown
+4. **Session patterns** — when they code (their peak hours), session count
+5. **Test discipline** — their personal test LOC ratio
+6. **Biggest ship** — their single highest-impact commit or PR in the window
+
+**For the current user ("You"):** This section gets the deepest treatment. Include all the detail from the solo retro — session analysis, time patterns, focus score. Frame it in first person: "Your peak hours...", "Your biggest ship..."
+
+**For each teammate:** Write 2-3 sentences covering what they worked on and their pattern. Then:
+
+- **Praise** (1-2 specific things): Anchor in actual commits. Not "great work" — say exactly what was good. Examples: "Shipped the entire auth middleware rewrite in 3 focused sessions with 45% test coverage", "Every PR under 200 LOC — disciplined decomposition."
+- **Opportunity for growth** (1 specific thing): Frame as a leveling-up suggestion, not criticism. Anchor in actual data. Examples: "Test ratio was 12% this week — adding test coverage to the payment module before it gets more complex would pay off", "5 fix commits on the same file suggest the original PR could have used a review pass."
+
+**If only one contributor (solo repo):** Skip the team breakdown and proceed as before — the retro is personal.
+
+**If there are Co-Authored-By trailers:** Parse `Co-Authored-By:` lines in commit messages. Credit those authors for the commit alongside the primary author. Note AI co-authors (e.g., `noreply@anthropic.com`) but do not include them as team members — instead, track "AI-assisted commits" as a separate metric.
+
+### Step 10: Week-over-Week Trends (if window >= 14d)
+
+If the time window is 14 days or more, split into weekly buckets and show trends:
+- Commits per week (total and per-author)
+- LOC per week
+- Test ratio per week
+- Fix ratio per week
+- Session count per week
+
+### Step 11: Streak Tracking
+
+Count consecutive days with at least 1 commit to origin/main, going back from today. Track both team streak and personal streak:
+
+```bash
+# Team streak: all unique commit dates (Pacific time) — no hard cutoff
+TZ=America/Los_Angeles git log origin/main --format="%ad" --date=format:"%Y-%m-%d" | sort -u
+
+# Personal streak: only the current user's commits
+TZ=America/Los_Angeles git log origin/main --author="<user_name>" --format="%ad" --date=format:"%Y-%m-%d" | sort -u
+```
+
+Count backward from today — how many consecutive days have at least one commit? This queries the full history so streaks of any length are reported accurately. Display both:
+- "Team shipping streak: 47 consecutive days"
+- "Your shipping streak: 32 consecutive days"
+
+### Step 12: Load History & Compare
+
+Before saving the new snapshot, check for prior retro history:
+
+```bash
+ls -t .context/retros/*.json 2>/dev/null
+```
+
+**If prior retros exist:** Load the most recent one using the Read tool. Calculate deltas for key metrics and include a **Trends vs Last Retro** section:
+```
+ Last Now Delta
+Test ratio: 22% → 41% ↑19pp
+Sessions: 10 → 14 ↑4
+LOC/hour: 200 → 350 ↑75%
+Fix ratio: 54% → 30% ↓24pp (improving)
+Commits: 32 → 47 ↑47%
+Deep sessions: 3 → 5 ↑2
+```
+
+**If no prior retros exist:** Skip the comparison section and append: "First retro recorded — run again next week to see trends."
+
+### Step 13: Save Retro History
+
+After computing all metrics (including streak) and loading any prior history for comparison, save a JSON snapshot:
+
+```bash
+mkdir -p .context/retros
+```
+
+Determine the next sequence number for today (substitute the actual date for `$(date +%Y-%m-%d)`):
+```bash
+# Count existing retros for today to get next sequence number
+today=$(TZ=America/Los_Angeles date +%Y-%m-%d)
+existing=$(ls .context/retros/${today}-*.json 2>/dev/null | wc -l | tr -d ' ')
+next=$((existing + 1))
+# Save as .context/retros/${today}-${next}.json
+```
+
+Use the Write tool to save the JSON file with this schema:
+```json
+{
+ "date": "2026-03-08",
+ "window": "7d",
+ "metrics": {
+ "commits": 47,
+ "contributors": 3,
+ "prs_merged": 12,
+ "insertions": 3200,
+ "deletions": 800,
+ "net_loc": 2400,
+ "test_loc": 1300,
+ "test_ratio": 0.41,
+ "active_days": 6,
+ "sessions": 14,
+ "deep_sessions": 5,
+ "avg_session_minutes": 42,
+ "loc_per_session_hour": 350,
+ "feat_pct": 0.40,
+ "fix_pct": 0.30,
+ "peak_hour": 22,
+ "ai_assisted_commits": 32
+ },
+ "authors": {
+ "Garry Tan": { "commits": 32, "insertions": 2400, "deletions": 300, "test_ratio": 0.41, "top_area": "browse/" },
+ "Alice": { "commits": 12, "insertions": 800, "deletions": 150, "test_ratio": 0.35, "top_area": "app/services/" }
+ },
+ "version_range": ["1.16.0.0", "1.16.1.0"],
+ "streak_days": 47,
+ "tweetable": "Week of Mar 1: 47 commits (3 contributors), 3.2k LOC, 38% tests, 12 PRs, peak: 10pm",
+ "greptile": {
+ "fixes": 3,
+ "fps": 1,
+ "already_fixed": 2,
+ "signal_pct": 83
+ }
+}
+```
+
+**Note:** Only include the `greptile` field if `~/.gstack/greptile-history.md` exists and has entries within the time window. If no history data is available, omit the field entirely.
+
+### Step 14: Write the Narrative
+
+Structure the output as:
+
+---
+
+**Tweetable summary** (first line, before everything else):
+```
+Week of Mar 1: 47 commits (3 contributors), 3.2k LOC, 38% tests, 12 PRs, peak: 10pm | Streak: 47d
+```
+
+## Engineering Retro: [date range]
+
+### Summary Table
+(from Step 2)
+
+### Trends vs Last Retro
+(from Step 11, loaded before save — skip if first retro)
+
+### Time & Session Patterns
+(from Steps 3-4)
+
+Narrative interpreting what the team-wide patterns mean:
+- When the most productive hours are and what drives them
+- Whether sessions are getting longer or shorter over time
+- Estimated hours per day of active coding (team aggregate)
+- Notable patterns: do team members code at the same time or in shifts?
+
+### Shipping Velocity
+(from Steps 5-7)
+
+Narrative covering:
+- Commit type mix and what it reveals
+- PR size discipline (are PRs staying small?)
+- Fix-chain detection (sequences of fix commits on the same subsystem)
+- Version bump discipline
+
+### Code Quality Signals
+- Test LOC ratio trend
+- Hotspot analysis (are the same files churning?)
+- Any XL PRs that should have been split
+- Greptile signal ratio and trend (if history exists): "Greptile: X% signal (Y valid catches, Z false positives)"
+
+### Focus & Highlights
+(from Step 8)
+- Focus score with interpretation
+- Ship of the week callout
+
+### Your Week (personal deep-dive)
+(from Step 9, for the current user only)
+
+This is the section the user cares most about. Include:
+- Their personal commit count, LOC, test ratio
+- Their session patterns and peak hours
+- Their focus areas
+- Their biggest ship
+- **What you did well** (2-3 specific things anchored in commits)
+- **Where to level up** (1-2 specific, actionable suggestions)
+
+### Team Breakdown
+(from Step 9, for each teammate — skip if solo repo)
+
+For each teammate (sorted by commits descending), write a section:
+
+#### [Name]
+- **What they shipped**: 2-3 sentences on their contributions, areas of focus, and commit patterns
+- **Praise**: 1-2 specific things they did well, anchored in actual commits. Be genuine — what would you actually say in a 1:1? Examples:
+ - "Cleaned up the entire auth module in 3 small, reviewable PRs — textbook decomposition"
+ - "Added integration tests for every new endpoint, not just happy paths"
+ - "Fixed the N+1 query that was causing 2s load times on the dashboard"
+- **Opportunity for growth**: 1 specific, constructive suggestion. Frame as investment, not criticism. Examples:
+ - "Test coverage on the payment module is at 8% — worth investing in before the next feature lands on top of it"
+ - "3 of the 5 PRs were 800+ LOC — breaking these up would catch issues earlier and make review easier"
+ - "All commits land between 1-4am — sustainable pace matters for code quality long-term"
+
+**AI collaboration note:** If many commits have `Co-Authored-By` AI trailers (e.g., Claude, Copilot), note the AI-assisted commit percentage as a team metric. Frame it neutrally — "N% of commits were AI-assisted" — without judgment.
+
+### Top 3 Team Wins
+Identify the 3 highest-impact things shipped in the window across the whole team. For each:
+- What it was
+- Who shipped it
+- Why it matters (product/architecture impact)
+
+### 3 Things to Improve
+Specific, actionable, anchored in actual commits. Mix personal and team-level suggestions. Phrase as "to get even better, the team could..."
+
+### 3 Habits for Next Week
+Small, practical, realistic. Each must be something that takes <5 minutes to adopt. At least one should be team-oriented (e.g., "review each other's PRs same-day").
+
+### Week-over-Week Trends
+(if applicable, from Step 10)
+
+---
+
+## Compare Mode
+
+When the user runs `/retro compare` (or `/retro compare 14d`):
+
+1. Compute metrics for the current window (default 7d) using `--since="7 days ago"`
+2. Compute metrics for the immediately prior same-length window using both `--since` and `--until` to avoid overlap (e.g., `--since="14 days ago" --until="7 days ago"` for a 7d window)
+3. Show a side-by-side comparison table with deltas and arrows
+4. Write a brief narrative highlighting the biggest improvements and regressions
+5. Save only the current-window snapshot to `.context/retros/` (same as a normal retro run); do **not** persist the prior-window metrics.
+
+## Tone
+
+- Encouraging but candid, no coddling
+- Specific and concrete — always anchor in actual commits/code
+- Skip generic praise ("great job!") — say exactly what was good and why
+- Frame improvements as leveling up, not criticism
+- **Praise should feel like something you'd actually say in a 1:1** — specific, earned, genuine
+- **Growth suggestions should feel like investment advice** — "this is worth your time because..." not "you failed at..."
+- Never compare teammates against each other negatively. Each person's section stands on its own.
+- Keep total output around 3000-4500 words (slightly longer to accommodate team sections)
+- Use markdown tables and code blocks for data, prose for narrative
+- Output directly to the conversation — do NOT write to filesystem (except the `.context/retros/` JSON snapshot)
+
+## Important Rules
+
+- ALL narrative output goes directly to the user in the conversation. The ONLY file written is the `.context/retros/` JSON snapshot.
+- Use `origin/main` for all git queries (not local main which may be stale)
+- Convert all timestamps to Pacific time for display (use `TZ=America/Los_Angeles`)
+- If the window has zero commits, say so and suggest a different window
+- Round LOC/hour to nearest 50
+- Treat merge commits as PR boundaries
+- Do not read CLAUDE.md or other docs — this skill is self-contained
+- On first run (no prior retros), skip comparison sections gracefully
M review/SKILL.md => review/SKILL.md +3 -1
@@ 13,12 13,14 @@ allowed-tools:
- Glob
- AskUserQuestion
---
+<!-- AUTO-GENERATED from SKILL.md.tmpl — do not edit directly -->
+<!-- Regenerate: bun run gen:skill-docs -->
## Update Check (run first)
```bash
_UPD=$(~/.claude/skills/gstack/bin/gstack-update-check 2>/dev/null || .claude/skills/gstack/bin/gstack-update-check 2>/dev/null || true)
-[ -n "$_UPD" ] && echo "$_UPD"
+[ -n "$_UPD" ] && echo "$_UPD" || true
```
If output shows `UPGRADE_AVAILABLE <old> <new>`: read `~/.claude/skills/gstack/gstack-upgrade/SKILL.md` and follow the "Inline upgrade flow" (AskUserQuestion → upgrade if yes, `touch ~/.gstack/last-update-check` if no). If `JUST_UPGRADED <from> <to>`: tell user "Running gstack v{to} (just updated!)" and continue.
A review/SKILL.md.tmpl => review/SKILL.md.tmpl +114 -0
@@ 0,0 1,114 @@
+---
+name: review
+version: 1.0.0
+description: |
+ Pre-landing PR review. Analyzes diff against main for SQL safety, LLM trust
+ boundary violations, conditional side effects, and other structural issues.
+allowed-tools:
+ - Bash
+ - Read
+ - Edit
+ - Write
+ - Grep
+ - Glob
+ - AskUserQuestion
+---
+
+{{UPDATE_CHECK}}
+
+# Pre-Landing PR Review
+
+You are running the `/review` workflow. Analyze the current branch's diff against main for structural issues that tests don't catch.
+
+---
+
+## Step 1: Check branch
+
+1. Run `git branch --show-current` to get the current branch.
+2. If on `main`, output: **"Nothing to review — you're on main or have no changes against main."** and stop.
+3. Run `git fetch origin main --quiet && git diff origin/main --stat` to check if there's a diff. If no diff, output the same message and stop.
+
+---
+
+## Step 2: Read the checklist
+
+Read `.claude/skills/review/checklist.md`.
+
+**If the file cannot be read, STOP and report the error.** Do not proceed without the checklist.
+
+---
+
+## Step 2.5: Check for Greptile review comments
+
+Read `.claude/skills/review/greptile-triage.md` and follow the fetch, filter, and classify steps.
+
+**If no PR exists, `gh` fails, API returns an error, or there are zero Greptile comments:** Skip this step silently. Greptile integration is additive — the review works without it.
+
+**If Greptile comments are found:** Store the classifications (VALID & ACTIONABLE, VALID BUT ALREADY FIXED, FALSE POSITIVE, SUPPRESSED) — you will need them in Step 5.
+
+---
+
+## Step 3: Get the diff
+
+Fetch the latest main to avoid false positives from a stale local main:
+
+```bash
+git fetch origin main --quiet
+```
+
+Run `git diff origin/main` to get the full diff. This includes both committed and uncommitted changes against the latest main.
+
+---
+
+## Step 4: Two-pass review
+
+Apply the checklist against the diff in two passes:
+
+1. **Pass 1 (CRITICAL):** SQL & Data Safety, LLM Output Trust Boundary
+2. **Pass 2 (INFORMATIONAL):** Conditional Side Effects, Magic Numbers & String Coupling, Dead Code & Consistency, LLM Prompt Issues, Test Gaps, View/Frontend
+
+Follow the output format specified in the checklist. Respect the suppressions — do NOT flag items listed in the "DO NOT flag" section.
+
+---
+
+## Step 5: Output findings
+
+**Always output ALL findings** — both critical and informational. The user must see every issue.
+
+- If CRITICAL issues found: output all findings, then for EACH critical issue use a separate AskUserQuestion with the problem, your recommended fix, and options (A: Fix it now, B: Acknowledge, C: False positive — skip).
+ After all critical questions are answered, output a summary of what the user chose for each issue. If the user chose A (fix) on any issue, apply the recommended fixes. If only B/C were chosen, no action needed.
+- If only non-critical issues found: output findings. No further action needed.
+- If no issues found: output `Pre-Landing Review: No issues found.`
+
+### Greptile comment resolution
+
+After outputting your own findings, if Greptile comments were classified in Step 2.5:
+
+**Include a Greptile summary in your output header:** `+ N Greptile comments (X valid, Y fixed, Z FP)`
+
+1. **VALID & ACTIONABLE comments:** These are already included in your CRITICAL findings — they follow the same AskUserQuestion flow (A: Fix it now, B: Acknowledge, C: False positive). If the user chooses C (false positive), post a reply using the appropriate API from the triage doc and save the pattern to both per-project and global greptile-history (see greptile-triage.md for write details).
+
+2. **FALSE POSITIVE comments:** Present each one via AskUserQuestion:
+ - Show the Greptile comment: file:line (or [top-level]) + body summary + permalink URL
+ - Explain concisely why it's a false positive
+ - Options:
+ - A) Reply to Greptile explaining why this is incorrect (recommended if clearly wrong)
+ - B) Fix it anyway (if low-effort and harmless)
+ - C) Ignore — don't reply, don't fix
+
+ If the user chooses A, post a reply using the appropriate API from the triage doc and save the pattern to both per-project and global greptile-history (see greptile-triage.md for write details).
+
+3. **VALID BUT ALREADY FIXED comments:** Reply acknowledging the catch — no AskUserQuestion needed:
+ - Post reply: `"Good catch — already fixed in <commit-sha>."`
+ - Save to both per-project and global greptile-history (see greptile-triage.md for write details)
+
+4. **SUPPRESSED comments:** Skip silently — these are known false positives from previous triage.
+
+---
+
+## Important Rules
+
+- **Read the FULL diff before commenting.** Do not flag issues already addressed in the diff.
+- **Read-only by default.** Only modify files if the user explicitly chooses "Fix it now" on a critical issue. Never commit, push, or create PRs.
+- **Be terse.** One line problem, one line fix. No preamble.
+- **Only flag real problems.** Skip anything that's fine.
M scripts/gen-skill-docs.ts => scripts/gen-skill-docs.ts +5 -0
@@ 177,6 177,11 @@ function findTemplates(): string[] {
path.join(ROOT, 'browse', 'SKILL.md.tmpl'),
path.join(ROOT, 'qa', 'SKILL.md.tmpl'),
path.join(ROOT, 'setup-browser-cookies', 'SKILL.md.tmpl'),
+ path.join(ROOT, 'ship', 'SKILL.md.tmpl'),
+ path.join(ROOT, 'review', 'SKILL.md.tmpl'),
+ path.join(ROOT, 'plan-ceo-review', 'SKILL.md.tmpl'),
+ path.join(ROOT, 'plan-eng-review', 'SKILL.md.tmpl'),
+ path.join(ROOT, 'retro', 'SKILL.md.tmpl'),
];
for (const p of candidates) {
if (fs.existsSync(p)) templates.push(p);
M ship/SKILL.md => ship/SKILL.md +3 -1
@@ 12,12 12,14 @@ allowed-tools:
- Glob
- AskUserQuestion
---
+<!-- AUTO-GENERATED from SKILL.md.tmpl — do not edit directly -->
+<!-- Regenerate: bun run gen:skill-docs -->
## Update Check (run first)
```bash
_UPD=$(~/.claude/skills/gstack/bin/gstack-update-check 2>/dev/null || .claude/skills/gstack/bin/gstack-update-check 2>/dev/null || true)
-[ -n "$_UPD" ] && echo "$_UPD"
+[ -n "$_UPD" ] && echo "$_UPD" || true
```
If output shows `UPGRADE_AVAILABLE <old> <new>`: read `~/.claude/skills/gstack/gstack-upgrade/SKILL.md` and follow the "Inline upgrade flow" (AskUserQuestion → upgrade if yes, `touch ~/.gstack/last-update-check` if no). If `JUST_UPGRADED <from> <to>`: tell user "Running gstack v{to} (just updated!)" and continue.
A ship/SKILL.md.tmpl => ship/SKILL.md.tmpl +345 -0
@@ 0,0 1,345 @@
+---
+name: ship
+version: 1.0.0
+description: |
+ Ship workflow: merge main, run tests, review diff, bump VERSION, update CHANGELOG, commit, push, create PR.
+allowed-tools:
+ - Bash
+ - Read
+ - Write
+ - Edit
+ - Grep
+ - Glob
+ - AskUserQuestion
+---
+
+{{UPDATE_CHECK}}
+
+# Ship: Fully Automated Ship Workflow
+
+You are running the `/ship` workflow. This is a **non-interactive, fully automated** workflow. Do NOT ask for confirmation at any step. The user said `/ship` which means DO IT. Run straight through and output the PR URL at the end.
+
+**Only stop for:**
+- On `main` branch (abort)
+- Merge conflicts that can't be auto-resolved (stop, show conflicts)
+- Test failures (stop, show failures)
+- Pre-landing review finds CRITICAL issues and user chooses to fix (not acknowledge or skip)
+- MINOR or MAJOR version bump needed (ask — see Step 4)
+- Greptile review comments that need user decision (complex fixes, false positives)
+
+**Never stop for:**
+- Uncommitted changes (always include them)
+- Version bump choice (auto-pick MICRO or PATCH — see Step 4)
+- CHANGELOG content (auto-generate from diff)
+- Commit message approval (auto-commit)
+- Multi-file changesets (auto-split into bisectable commits)
+
+---
+
+## Step 1: Pre-flight
+
+1. Check the current branch. If on `main`, **abort**: "You're on main. Ship from a feature branch."
+
+2. Run `git status` (never use `-uall`). Uncommitted changes are always included — no need to ask.
+
+3. Run `git diff main...HEAD --stat` and `git log main..HEAD --oneline` to understand what's being shipped.
+
+---
+
+## Step 2: Merge origin/main (BEFORE tests)
+
+Fetch and merge `origin/main` into the feature branch so tests run against the merged state:
+
+```bash
+git fetch origin main && git merge origin/main --no-edit
+```
+
+**If there are merge conflicts:** Try to auto-resolve if they are simple (VERSION, schema.rb, CHANGELOG ordering). If conflicts are complex or ambiguous, **STOP** and show them.
+
+**If already up to date:** Continue silently.
+
+---
+
+## Step 3: Run tests (on merged code)
+
+**Do NOT run `RAILS_ENV=test bin/rails db:migrate`** — `bin/test-lane` already calls
+`db:test:prepare` internally, which loads the schema into the correct lane database.
+Running bare test migrations without INSTANCE hits an orphan DB and corrupts structure.sql.
+
+Run both test suites in parallel:
+
+```bash
+bin/test-lane 2>&1 | tee /tmp/ship_tests.txt &
+npm run test 2>&1 | tee /tmp/ship_vitest.txt &
+wait
+```
+
+After both complete, read the output files and check pass/fail.
+
+**If any test fails:** Show the failures and **STOP**. Do not proceed.
+
+**If all pass:** Continue silently — just note the counts briefly.
+
+---
+
+## Step 3.25: Eval Suites (conditional)
+
+Evals are mandatory when prompt-related files change. Skip this step entirely if no prompt files are in the diff.
+
+**1. Check if the diff touches prompt-related files:**
+
+```bash
+git diff origin/main --name-only
+```
+
+Match against these patterns (from CLAUDE.md):
+- `app/services/*_prompt_builder.rb`
+- `app/services/*_generation_service.rb`, `*_writer_service.rb`, `*_designer_service.rb`
+- `app/services/*_evaluator.rb`, `*_scorer.rb`, `*_classifier_service.rb`, `*_analyzer.rb`
+- `app/services/concerns/*voice*.rb`, `*writing*.rb`, `*prompt*.rb`, `*token*.rb`
+- `app/services/chat_tools/*.rb`, `app/services/x_thread_tools/*.rb`
+- `config/system_prompts/*.txt`
+- `test/evals/**/*` (eval infrastructure changes affect all suites)
+
+**If no matches:** Print "No prompt-related files changed — skipping evals." and continue to Step 3.5.
+
+**2. Identify affected eval suites:**
+
+Each eval runner (`test/evals/*_eval_runner.rb`) declares `PROMPT_SOURCE_FILES` listing which source files affect it. Grep these to find which suites match the changed files:
+
+```bash
+grep -l "changed_file_basename" test/evals/*_eval_runner.rb
+```
+
+Map runner → test file: `post_generation_eval_runner.rb` → `post_generation_eval_test.rb`.
+
+**Special cases:**
+- Changes to `test/evals/judges/*.rb`, `test/evals/support/*.rb`, or `test/evals/fixtures/` affect ALL suites that use those judges/support files. Check imports in the eval test files to determine which.
+- Changes to `config/system_prompts/*.txt` — grep eval runners for the prompt filename to find affected suites.
+- If unsure which suites are affected, run ALL suites that could plausibly be impacted. Over-testing is better than missing a regression.
+
+**3. Run affected suites at `EVAL_JUDGE_TIER=full`:**
+
+`/ship` is a pre-merge gate, so always use full tier (Sonnet structural + Opus persona judges).
+
+```bash
+EVAL_JUDGE_TIER=full EVAL_VERBOSE=1 bin/test-lane --eval test/evals/<suite>_eval_test.rb 2>&1 | tee /tmp/ship_evals.txt
+```
+
+If multiple suites need to run, run them sequentially (each needs a test lane). If the first suite fails, stop immediately — don't burn API cost on remaining suites.
+
+**4. Check results:**
+
+- **If any eval fails:** Show the failures, the cost dashboard, and **STOP**. Do not proceed.
+- **If all pass:** Note pass counts and cost. Continue to Step 3.5.
+
+**5. Save eval output** — include eval results and cost dashboard in the PR body (Step 8).
+
+**Tier reference (for context — /ship always uses `full`):**
+| Tier | When | Speed (cached) | Cost |
+|------|------|----------------|------|
+| `fast` (Haiku) | Dev iteration, smoke tests | ~5s (14x faster) | ~$0.07/run |
+| `standard` (Sonnet) | Default dev, `bin/test-lane --eval` | ~17s (4x faster) | ~$0.37/run |
+| `full` (Opus persona) | **`/ship` and pre-merge** | ~72s (baseline) | ~$1.27/run |
+
+---
+
+## Step 3.5: Pre-Landing Review
+
+Review the diff for structural issues that tests don't catch.
+
+1. Read `.claude/skills/review/checklist.md`. If the file cannot be read, **STOP** and report the error.
+
+2. Run `git diff origin/main` to get the full diff (scoped to feature changes against the freshly-fetched remote main).
+
+3. Apply the review checklist in two passes:
+ - **Pass 1 (CRITICAL):** SQL & Data Safety, LLM Output Trust Boundary
+ - **Pass 2 (INFORMATIONAL):** All remaining categories
+
+4. **Always output ALL findings** — both critical and informational. The user must see every issue found.
+
+5. Output a summary header: `Pre-Landing Review: N issues (X critical, Y informational)`
+
+6. **If CRITICAL issues found:** For EACH critical issue, use a separate AskUserQuestion with:
+ - The problem (`file:line` + description)
+ - Your recommended fix
+ - Options: A) Fix it now (recommend), B) Acknowledge and ship anyway, C) It's a false positive — skip
+ After resolving all critical issues: if the user chose A (fix) on any issue, apply the recommended fixes, then commit only the fixed files by name (`git add <fixed-files> && git commit -m "fix: apply pre-landing review fixes"`), then **STOP** and tell the user to run `/ship` again to re-test with the fixes applied. If the user chose only B (acknowledge) or C (false positive) on all issues, continue with Step 4.
+
+7. **If only non-critical issues found:** Output them and continue. They will be included in the PR body at Step 8.
+
+8. **If no issues found:** Output `Pre-Landing Review: No issues found.` and continue.
+
+Save the review output — it goes into the PR body in Step 8.
+
+---
+
+## Step 3.75: Address Greptile review comments (if PR exists)
+
+Read `.claude/skills/review/greptile-triage.md` and follow the fetch, filter, and classify steps.
+
+**If no PR exists, `gh` fails, API returns an error, or there are zero Greptile comments:** Skip this step silently. Continue to Step 4.
+
+**If Greptile comments are found:**
+
+Include a Greptile summary in your output: `+ N Greptile comments (X valid, Y fixed, Z FP)`
+
+For each classified comment:
+
+**VALID & ACTIONABLE:** Use AskUserQuestion with:
+- The comment (file:line or [top-level] + body summary + permalink URL)
+- Your recommended fix
+- Options: A) Fix now (recommended), B) Acknowledge and ship anyway, C) It's a false positive
+- If user chooses A: apply the fix, commit the fixed files (`git add <fixed-files> && git commit -m "fix: address Greptile review — <brief description>"`), reply to the comment (`"Fixed in <commit-sha>."`), and save to both per-project and global greptile-history (see greptile-triage.md for write details, type: fix).
+- If user chooses C: reply explaining the false positive, save to both per-project and global greptile-history (type: fp).
+
+**VALID BUT ALREADY FIXED:** Reply acknowledging the catch — no AskUserQuestion needed:
+- Post reply: `"Good catch — already fixed in <commit-sha>."`
+- Save to both per-project and global greptile-history (see greptile-triage.md for write details, type: already-fixed)
+
+**FALSE POSITIVE:** Use AskUserQuestion:
+- Show the comment and why you think it's wrong (file:line or [top-level] + body summary + permalink URL)
+- Options:
+ - A) Reply to Greptile explaining the false positive (recommended if clearly wrong)
+ - B) Fix it anyway (if trivial)
+ - C) Ignore silently
+- If user chooses A: post reply using the appropriate API from the triage doc, save to both per-project and global greptile-history (type: fp)
+
+**SUPPRESSED:** Skip silently — these are known false positives from previous triage.
+
+**After all comments are resolved:** If any fixes were applied, the tests from Step 3 are now stale. **Re-run tests** (Step 3) before continuing to Step 4. If no fixes were applied, continue to Step 4.
+
+---
+
+## Step 4: Version bump (auto-decide)
+
+1. Read the current `VERSION` file (4-digit format: `MAJOR.MINOR.PATCH.MICRO`)
+
+2. **Auto-decide the bump level based on the diff:**
+ - Count lines changed (`git diff origin/main...HEAD --stat | tail -1`)
+ - **MICRO** (4th digit): < 50 lines changed, trivial tweaks, typos, config
+ - **PATCH** (3rd digit): 50+ lines changed, bug fixes, small-medium features
+ - **MINOR** (2nd digit): **ASK the user** — only for major features or significant architectural changes
+ - **MAJOR** (1st digit): **ASK the user** — only for milestones or breaking changes
+
+3. Compute the new version:
+ - Bumping a digit resets all digits to its right to 0
+ - Example: `0.19.1.0` + PATCH → `0.19.2.0`
+
+4. Write the new version to the `VERSION` file.
+
+---
+
+## Step 5: CHANGELOG (auto-generate)
+
+1. Read `CHANGELOG.md` header to know the format.
+
+2. Auto-generate the entry from **ALL commits on the branch** (not just recent ones):
+ - Use `git log main..HEAD --oneline` to see every commit being shipped
+ - Use `git diff main...HEAD` to see the full diff against main
+ - The CHANGELOG entry must be comprehensive of ALL changes going into the PR
+ - If existing CHANGELOG entries on the branch already cover some commits, replace them with one unified entry for the new version
+ - Categorize changes into applicable sections:
+ - `### Added` — new features
+ - `### Changed` — changes to existing functionality
+ - `### Fixed` — bug fixes
+ - `### Removed` — removed features
+ - Write concise, descriptive bullet points
+ - Insert after the file header (line 5), dated today
+ - Format: `## [X.Y.Z.W] - YYYY-MM-DD`
+
+**Do NOT ask the user to describe changes.** Infer from the diff and commit history.
+
+---
+
+## Step 6: Commit (bisectable chunks)
+
+**Goal:** Create small, logical commits that work well with `git bisect` and help LLMs understand what changed.
+
+1. Analyze the diff and group changes into logical commits. Each commit should represent **one coherent change** — not one file, but one logical unit.
+
+2. **Commit ordering** (earlier commits first):
+ - **Infrastructure:** migrations, config changes, route additions
+ - **Models & services:** new models, services, concerns (with their tests)
+ - **Controllers & views:** controllers, views, JS/React components (with their tests)
+ - **VERSION + CHANGELOG:** always in the final commit
+
+3. **Rules for splitting:**
+ - A model and its test file go in the same commit
+ - A service and its test file go in the same commit
+ - A controller, its views, and its test go in the same commit
+ - Migrations are their own commit (or grouped with the model they support)
+ - Config/route changes can group with the feature they enable
+ - If the total diff is small (< 50 lines across < 4 files), a single commit is fine
+
+4. **Each commit must be independently valid** — no broken imports, no references to code that doesn't exist yet. Order commits so dependencies come first.
+
+5. Compose each commit message:
+ - First line: `<type>: <summary>` (type = feat/fix/chore/refactor/docs)
+ - Body: brief description of what this commit contains
+ - Only the **final commit** (VERSION + CHANGELOG) gets the version tag and co-author trailer:
+
+```bash
+git commit -m "$(cat <<'EOF'
+chore: bump version and changelog (vX.Y.Z.W)
+
+Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
+EOF
+)"
+```
+
+---
+
+## Step 7: Push
+
+Push to the remote with upstream tracking:
+
+```bash
+git push -u origin <branch-name>
+```
+
+---
+
+## Step 8: Create PR
+
+Create a pull request using `gh`:
+
+```bash
+gh pr create --title "<type>: <summary>" --body "$(cat <<'EOF'
+## Summary
+<bullet points from CHANGELOG>
+
+## Pre-Landing Review
+<findings from Step 3.5, or "No issues found.">
+
+## Eval Results
+<If evals ran: suite names, pass/fail counts, cost dashboard summary. If skipped: "No prompt-related files changed — evals skipped.">
+
+## Greptile Review
+<If Greptile comments were found: bullet list with [FIXED] / [FALSE POSITIVE] / [ALREADY FIXED] tag + one-line summary per comment>
+<If no Greptile comments found: "No Greptile comments.">
+<If no PR existed during Step 3.75: omit this section entirely>
+
+## Test plan
+- [x] All Rails tests pass (N runs, 0 failures)
+- [x] All Vitest tests pass (N tests)
+
+🤖 Generated with [Claude Code](https://claude.com/claude-code)
+EOF
+)"
+```
+
+**Output the PR URL** — this should be the final output the user sees.
+
+---
+
+## Important Rules
+
+- **Never skip tests.** If tests fail, stop.
+- **Never skip the pre-landing review.** If checklist.md is unreadable, stop.
+- **Never force push.** Use regular `git push` only.
+- **Never ask for confirmation** except for MINOR/MAJOR version bumps and CRITICAL review findings (one AskUserQuestion per critical issue with fix recommendation).
+- **Always use the 4-digit version format** from the VERSION file.
+- **Date format in CHANGELOG:** `YYYY-MM-DD`
+- **Split commits for bisectability** — each commit = one logical change.
+- **The goal is: user says `/ship`, next thing they see is the review + PR URL.**
M test/skill-validation.test.ts => test/skill-validation.test.ts +46 -0
@@ 152,6 152,52 @@ describe('Generated SKILL.md freshness', () => {
});
});
+// --- Update check preamble validation ---
+
+describe('Update check preamble', () => {
+ const skillsWithUpdateCheck = [
+ 'SKILL.md', 'browse/SKILL.md', 'qa/SKILL.md',
+ 'setup-browser-cookies/SKILL.md',
+ 'ship/SKILL.md', 'review/SKILL.md',
+ 'plan-ceo-review/SKILL.md', 'plan-eng-review/SKILL.md',
+ 'retro/SKILL.md',
+ ];
+
+ for (const skill of skillsWithUpdateCheck) {
+ test(`${skill} update check line ends with || true`, () => {
+ const content = fs.readFileSync(path.join(ROOT, skill), 'utf-8');
+ // The second line of the bash block must end with || true
+ // to avoid exit code 1 when _UPD is empty (up to date)
+ const match = content.match(/\[ -n "\$_UPD" \].*$/m);
+ expect(match).not.toBeNull();
+ expect(match![0]).toContain('|| true');
+ });
+ }
+
+ test('all skills with update check are generated from .tmpl', () => {
+ for (const skill of skillsWithUpdateCheck) {
+ const tmplPath = path.join(ROOT, skill + '.tmpl');
+ expect(fs.existsSync(tmplPath)).toBe(true);
+ }
+ });
+
+ test('update check bash block exits 0 when up to date', () => {
+ // Simulate the exact preamble command from SKILL.md
+ const result = Bun.spawnSync(['bash', '-c',
+ '_UPD=$(echo "" || true); [ -n "$_UPD" ] && echo "$_UPD" || true'
+ ], { stdout: 'pipe', stderr: 'pipe' });
+ expect(result.exitCode).toBe(0);
+ });
+
+ test('update check bash block exits 0 when upgrade available', () => {
+ const result = Bun.spawnSync(['bash', '-c',
+ '_UPD=$(echo "UPGRADE_AVAILABLE 0.3.3 0.4.0" || true); [ -n "$_UPD" ] && echo "$_UPD" || true'
+ ], { stdout: 'pipe', stderr: 'pipe' });
+ expect(result.exitCode).toBe(0);
+ expect(result.stdout.toString().trim()).toBe('UPGRADE_AVAILABLE 0.3.3 0.4.0');
+ });
+});
+
// --- Part 7: Cross-skill path consistency (A1) ---
describe('Cross-skill path consistency', () => {