continuous-improvement 3.8.0 → 3.9.2

package/skills/ralph.md

@@ -1,221 +1,221 @@
----
-name: ralph
-tier: companion
-description: "Enforces Law 6 (Iterate Means One Thing) of the 7 Laws of AI Agent Discipline at PRD scale. Ralph is an autonomous AI agent loop that runs repeatedly until all PRD items are complete. Converts PRDs to executable JSON, implements stories iteratively with quality checks, and tracks progress."
-origin: https://github.com/snarktank/ralph
----
-
-# Ralph — Autonomous Agent Loop
-
-Ralph runs iteratively until all PRD stories are complete. Each iteration: picks highest priority story, implements, runs quality checks, commits if passing, updates progress, repeats.
-
-## When to Use
-
-- Large features that exceed a single context window
-- Multi-story PRDs that need consistent implementation
-- Tasks requiring repeated verification and commit cycles
-- Long-running development that benefits from persistence across interruptions
-
-## Do NOT Use When
-
-- Task is a one-shot fix completable in a single edit — just edit the file
-- You haven't written a PRD yet — write the PRD first, then run Ralph against it
-- The work spans fewer than 3 stories — single-iteration verification is enough
-- You need to explore or plan before committing to scope — use a planning skill first; Ralph is for execution, not discovery
-- You want manual control over each iteration — run quality checks yourself, no need for Ralph's loop
-
-## Prerequisites
-
-- Git repository
-- PRD document (markdown format)
-- `jq` installed (`brew install jq` on macOS)
-
-## Workflow
-
-### 1. Create a PRD
-
-Generate a detailed requirements document using the PRD skill:
-
-```
-Load the prd skill and create a PRD for [your feature description]
-```
-
-Output saved to `tasks/prd-[feature-name].md`
-
-**CRITICAL — refine generic criteria before iteration begins.** Auto-generated PRD scaffolds often produce generic acceptance criteria like `["Implementation is complete", "Code compiles without errors"]`. These are theater — Ralph cannot prove a story passes against criteria that don't actually constrain it. Replace every generic criterion with a concrete, testable statement before moving to step 2.
-
-- Bad: `"Function is implemented correctly"`
-- Good: `"Function parseUserInput(s) returns {ok: true, value} for valid s and {ok: false, error} for invalid s, asserted by tests/parse-user-input.test.ts"`
-- Bad: `"Code compiles"`
-- Good: `"TypeScript compiles with no errors (npm run build) AND lsp diagnostics show 0 errors on src/parse-user-input.ts"`
-
-If you cannot write a testable criterion, the story is too big. Break it down before continuing.
-
-**Example — refining a scaffold criterion**
-
-Auto-generated:
-
-```json
-"acceptanceCriteria": [
-  "Implementation is complete",
-  "Code compiles without errors"
-]
-```
-
-After refinement:
-
-```json
-"acceptanceCriteria": [
-  "POST /api/users returns 201 with {id, email} for valid input, asserted by tests/api-users.test.ts",
-  "POST /api/users returns 400 with {error} for missing email, asserted by tests/api-users.test.ts",
-  "TypeScript compiles with 0 errors (npm run build)",
-  "lsp diagnostics show 0 errors on src/api/users.ts"
-]
-```
-
-### 2. Convert PRD to Ralph Format
-
-Convert the markdown PRD to executable JSON:
-
-```
-Load the ralph skill and convert tasks/prd-[feature-name].md to prd.json
-```
-
-This creates `prd.json` with user stories structured for autonomous execution.
-
-### 3. Run Ralph
-
-Execute the autonomous loop:
-
-```bash
-# Using Amp (default)
-./scripts/ralph/ralph.sh [max_iterations]
-
-# Using Claude Code
-./scripts/ralph/ralph.sh --tool claude [max_iterations]
-```
-
-Default: 10 iterations. Use `--tool amp` or `--tool claude` to select your AI tool.
-
-## Ralph Loop Steps
-
-1. **Create feature branch** — from PRD `branchName`
-2. **Pick highest priority story** — where `passes: false`
-3. **Implement that single story** — fresh context per iteration
-4. **Run quality checks** — verify the current story's specific acceptance criteria with fresh evidence:
-   - For EACH acceptance criterion, run the test/build/lint that proves it
-   - Read the output, do not assume
-   - If ANY criterion is not met, continue working — do NOT mark the story as `passes: true`
-   - **Suite-level "all tests pass" is NOT a substitute for criterion-level proof.**
-
-   **Example — story-by-story verification**
-
-   Bad:
-
-   ```
-   Story US-002: "Add /api/users endpoint"
-   - Ran npm test → all green → marked passes: true
-   ```
-
-   Why bad: suite-level pass doesn't prove THIS story's criteria. Other tests could be passing while the new endpoint is broken.
-
-   Good:
-
-   ```
-   Story US-002: "Add /api/users endpoint"
-   - Criterion 1: POST /api/users → 201 → ran `npx vitest tests/api-users.test.ts -t "valid input"` → PASS
-   - Criterion 2: POST /api/users → 400 → ran `npx vitest tests/api-users.test.ts -t "missing email"` → PASS
-   - Criterion 3: typecheck → ran `npm run build` → 0 errors
-   - All criteria met with fresh evidence → marked passes: true
-   ```
-
-   Why good: each criterion proven with a targeted run; the output was read before the mark.
-
-5. **Commit if checks pass** — atomic commits per story
-6. **Update prd.json** — mark story as `passes: true`
-7. **Append learnings** — to `progress.txt`
-8. **Repeat** — until all stories pass or max iterations reached
-
-## Key Concepts
-
-### Each Iteration = Fresh Context
-
-Every story gets a clean slate. Previous work is visible only via git history and `prd.json`, preventing context pollution.
-
-### Small Tasks
-
-Stories should be completable in 10-30 minutes. If a story stalls, break it down.
-
-### AGENTS.md Updates Are Critical
-
-Ralph updates `AGENTS.md` after each story so subsequent iterations know what's already done.
-
-### Feedback Loops
-
-- Build/test failures: immediate fix or rollback
-- Test failures: investigate before declaring pass
-- Confusion: log to `progress.txt` for human review
-
-### Browser Verification for UI Stories
-
-Ralph starts a dev server and uses Playwright to verify UI stories actually render.
-
-### Stop Condition
-
-Ralph stops when:
-- All stories have `passes: true`
-- Max iterations reached
-- Critical failure encountered (user intervention required)
-
-## Anti-patterns
-
-These thoughts mean STOP — Ralph is about to slip:
-
-| Thought | Why it's wrong |
-|---|---|
-| "All stories pass, time to summarise and wait for the user" mid-loop | Polite-stop. Ralph continues through commit + progress update + next pick in the same turn. |
-| "Tests pass at the suite level, the story must be done" | Suite-level pass is not criterion-level proof. Verify each criterion with fresh evidence. |
-| "Story is bigger than expected, I'll mark it passes: true and add a TODO" | Scope reduction. Either complete the story or break it down — never declare partial completion. |
-| "The criterion is generic but obviously the test covers it" | PRD theater. Refine the criterion to something specific before proceeding. |
-| "I'll skip the failing test by deleting/skipping it" | Tests are evidence. Fix the implementation, not the test. |
-| "Reviewer said it looks good" — without running fresh checks | "Looks good" is not verification. Run the build, run the tests, read the output. |
-
-## Final Checklist (Hard Gate)
-
-Ralph cannot exit cleanly until ALL of these are true:
-
-- [ ] Every story in `prd.json` has `passes: true` (no incomplete stories)
-- [ ] Acceptance criteria are task-specific (no `"Implementation is complete"` generics)
-- [ ] All requirements from the original task are met (no scope reduction)
-- [ ] Fresh test run output shows all tests pass (read it, don't assume)
-- [ ] Fresh build output shows success (read it, don't assume)
-- [ ] No tests were deleted, skipped, or weakened to make checks green
-- [ ] `progress.txt` records implementation details and learnings per iteration
-- [ ] Working tree is clean (every story committed atomically)
-
-A failing checkbox is a hard halt — do not declare done.
-
-## Files
-
-- `prd.json` — executable PRD with user stories
-- `progress.txt` — accumulated learnings and status
-- `ralph.sh` — the loop script
-- `AGENTS.md` — iteration memory
-
-## Debugging
-
-If Ralph gets stuck:
-
-1. Check `prd.json` for malformed stories
-2. Review `progress.txt` for accumulated errors
-3. Verify tests pass independently: `npm test` or equivalent
-4. Check git status for uncommitted changes
-5. Run single iteration manually to isolate issues
-
-## Customizing the Prompt
-
-Edit the prompt template in `scripts/ralph/prompt.md` (Amp) or `scripts/ralph/CLAUDE.md` (Claude Code) to adjust behavior.
-
-## Archiving
-
-After completion, archive `prd.json` and `progress.txt` to `tasks/archive/[date]/` for future reference.
+---
+name: ralph
+tier: companion
+description: "Enforces Law 6 (Iterate Means One Thing) of the 7 Laws of AI Agent Discipline at PRD scale. Ralph is an autonomous AI agent loop that runs repeatedly until all PRD items are complete. Converts PRDs to executable JSON, implements stories iteratively with quality checks, and tracks progress."
+origin: https://github.com/snarktank/ralph
+---
+
+# Ralph — Autonomous Agent Loop
+
+Ralph runs iteratively until all PRD stories are complete. Each iteration: picks highest priority story, implements, runs quality checks, commits if passing, updates progress, repeats.
+
+## When to Use
+
+- Large features that exceed a single context window
+- Multi-story PRDs that need consistent implementation
+- Tasks requiring repeated verification and commit cycles
+- Long-running development that benefits from persistence across interruptions
+
+## Do NOT Use When
+
+- Task is a one-shot fix completable in a single edit — just edit the file
+- You haven't written a PRD yet — write the PRD first, then run Ralph against it
+- The work spans fewer than 3 stories — single-iteration verification is enough
+- You need to explore or plan before committing to scope — use a planning skill first; Ralph is for execution, not discovery
+- You want manual control over each iteration — run quality checks yourself, no need for Ralph's loop
+
+## Prerequisites
+
+- Git repository
+- PRD document (markdown format)
+- `jq` installed (`brew install jq` on macOS)
+
+## Workflow
+
+### 1. Create a PRD
+
+Generate a detailed requirements document using the PRD skill:
+
+```
+Load the prd skill and create a PRD for [your feature description]
+```
+
+Output saved to `tasks/prd-[feature-name].md`
+
+**CRITICAL — refine generic criteria before iteration begins.** Auto-generated PRD scaffolds often produce generic acceptance criteria like `["Implementation is complete", "Code compiles without errors"]`. These are theater — Ralph cannot prove a story passes against criteria that don't actually constrain it. Replace every generic criterion with a concrete, testable statement before moving to step 2.
+
+- Bad: `"Function is implemented correctly"`
+- Good: `"Function parseUserInput(s) returns {ok: true, value} for valid s and {ok: false, error} for invalid s, asserted by tests/parse-user-input.test.ts"`
+- Bad: `"Code compiles"`
+- Good: `"TypeScript compiles with no errors (npm run build) AND lsp diagnostics show 0 errors on src/parse-user-input.ts"`
+
+If you cannot write a testable criterion, the story is too big. Break it down before continuing.
+
+**Example — refining a scaffold criterion**
+
+Auto-generated:
+
+```json
+"acceptanceCriteria": [
+  "Implementation is complete",
+  "Code compiles without errors"
+]
+```
+
+After refinement:
+
+```json
+"acceptanceCriteria": [
+  "POST /api/users returns 201 with {id, email} for valid input, asserted by tests/api-users.test.ts",
+  "POST /api/users returns 400 with {error} for missing email, asserted by tests/api-users.test.ts",
+  "TypeScript compiles with 0 errors (npm run build)",
+  "lsp diagnostics show 0 errors on src/api/users.ts"
+]
+```
+
+### 2. Convert PRD to Ralph Format
+
+Convert the markdown PRD to executable JSON:
+
+```
+Load the ralph skill and convert tasks/prd-[feature-name].md to prd.json
+```
+
+This creates `prd.json` with user stories structured for autonomous execution.
+
+### 3. Run Ralph
+
+Execute the autonomous loop:
+
+```bash
+# Using Amp (default)
+./scripts/ralph/ralph.sh [max_iterations]
+
+# Using Claude Code
+./scripts/ralph/ralph.sh --tool claude [max_iterations]
+```
+
+Default: 10 iterations. Use `--tool amp` or `--tool claude` to select your AI tool.
+
+## Ralph Loop Steps
+
+1. **Create feature branch** — from PRD `branchName`
+2. **Pick highest priority story** — where `passes: false`
+3. **Implement that single story** — fresh context per iteration
+4. **Run quality checks** — verify the current story's specific acceptance criteria with fresh evidence:
+   - For EACH acceptance criterion, run the test/build/lint that proves it
+   - Read the output, do not assume
+   - If ANY criterion is not met, continue working — do NOT mark the story as `passes: true`
+   - **Suite-level "all tests pass" is NOT a substitute for criterion-level proof.**
+
+   **Example — story-by-story verification**
+
+   Bad:
+
+   ```
+   Story US-002: "Add /api/users endpoint"
+   - Ran npm test → all green → marked passes: true
+   ```
+
+   Why bad: suite-level pass doesn't prove THIS story's criteria. Other tests could be passing while the new endpoint is broken.
+
+   Good:
+
+   ```
+   Story US-002: "Add /api/users endpoint"
+   - Criterion 1: POST /api/users → 201 → ran `npx vitest tests/api-users.test.ts -t "valid input"` → PASS
+   - Criterion 2: POST /api/users → 400 → ran `npx vitest tests/api-users.test.ts -t "missing email"` → PASS
+   - Criterion 3: typecheck → ran `npm run build` → 0 errors
+   - All criteria met with fresh evidence → marked passes: true
+   ```
+
+   Why good: each criterion proven with a targeted run; the output was read before the mark.
+
+5. **Commit if checks pass** — atomic commits per story
+6. **Update prd.json** — mark story as `passes: true`
+7. **Append learnings** — to `progress.txt`
+8. **Repeat** — until all stories pass or max iterations reached
+
+## Key Concepts
+
+### Each Iteration = Fresh Context
+
+Every story gets a clean slate. Previous work is visible only via git history and `prd.json`, preventing context pollution.
+
+### Small Tasks
+
+Stories should be completable in 10-30 minutes. If a story stalls, break it down.
+
+### AGENTS.md Updates Are Critical
+
+Ralph updates `AGENTS.md` after each story so subsequent iterations know what's already done.
+
+### Feedback Loops
+
+- Build/test failures: immediate fix or rollback
+- Test failures: investigate before declaring pass
+- Confusion: log to `progress.txt` for human review
+
+### Browser Verification for UI Stories
+
+Ralph starts a dev server and uses Playwright to verify UI stories actually render.
+
+### Stop Condition
+
+Ralph stops when:
+- All stories have `passes: true`
+- Max iterations reached
+- Critical failure encountered (user intervention required)
+
+## Anti-patterns
+
+These thoughts mean STOP — Ralph is about to slip:
+
+| Thought | Why it's wrong |
+|---|---|
+| "All stories pass, time to summarise and wait for the user" mid-loop | Polite-stop. Ralph continues through commit + progress update + next pick in the same turn. |
+| "Tests pass at the suite level, the story must be done" | Suite-level pass is not criterion-level proof. Verify each criterion with fresh evidence. |
+| "Story is bigger than expected, I'll mark it passes: true and add a TODO" | Scope reduction. Either complete the story or break it down — never declare partial completion. |
+| "The criterion is generic but obviously the test covers it" | PRD theater. Refine the criterion to something specific before proceeding. |
+| "I'll skip the failing test by deleting/skipping it" | Tests are evidence. Fix the implementation, not the test. |
+| "Reviewer said it looks good" — without running fresh checks | "Looks good" is not verification. Run the build, run the tests, read the output. |
+
+## Final Checklist (Hard Gate)
+
+Ralph cannot exit cleanly until ALL of these are true:
+
+- [ ] Every story in `prd.json` has `passes: true` (no incomplete stories)
+- [ ] Acceptance criteria are task-specific (no `"Implementation is complete"` generics)
+- [ ] All requirements from the original task are met (no scope reduction)
+- [ ] Fresh test run output shows all tests pass (read it, don't assume)
+- [ ] Fresh build output shows success (read it, don't assume)
+- [ ] No tests were deleted, skipped, or weakened to make checks green
+- [ ] `progress.txt` records implementation details and learnings per iteration
+- [ ] Working tree is clean (every story committed atomically)
+
+A failing checkbox is a hard halt — do not declare done.
+
+## Files
+
+- `prd.json` — executable PRD with user stories
+- `progress.txt` — accumulated learnings and status
+- `ralph.sh` — the loop script
+- `AGENTS.md` — iteration memory
+
+## Debugging
+
+If Ralph gets stuck:
+
+1. Check `prd.json` for malformed stories
+2. Review `progress.txt` for accumulated errors
+3. Verify tests pass independently: `npm test` or equivalent
+4. Check git status for uncommitted changes
+5. Run single iteration manually to isolate issues
+
+## Customizing the Prompt
+
+Edit the prompt template in `scripts/ralph/prompt.md` (Amp) or `scripts/ralph/CLAUDE.md` (Claude Code) to adjust behavior.
+
+## Archiving
+
+After completion, archive `prd.json` and `progress.txt` to `tasks/archive/[date]/` for future reference.

package/skills/recovery-classification.md

@@ -0,0 +1,73 @@
+---
+name: recovery-classification
+tier: "2"
+description: "Enforces Law 4 (Verify Before Reporting) of the 7 Laws of AI Agent Discipline. After any failure in the verification ladder or auto-loop, classify the failure class before retrying — provider, tool-schema, deterministic-policy, git, worktree, runtime — so retry-vs-pause-vs-self-heal-vs-stop is an intentional decision, not a generic 'try again'."
+origin: continuous-improvement
+---
+
+# Recovery Classification Skill
+
+When a phase or unit fails, name the failure class first. Generic "retry on failure" hides repeatable failure modes and turns them into flaky tests.
+
+## When to Use
+
+- After any Phase 1–6 failure in `verification-loop`.
+- After any auto-loop unit that exits non-zero.
+- After any tool call the harness rejects (schema validation, policy gate, deterministic block).
+- Before re-running anything that just failed — classification fires once, before the first retry.
+
+## Why This Skill Exists
+
+GSD-2's [CONTEXT.md](https://github.com/gsd-build/gsd-2/blob/main/CONTEXT.md) names "Recovery Classification" as one of four runtime invariant modules. Common failure modes it catches:
+
+- **Deterministic-policy blocks misclassified as generic provider failures** — gateguard denials retried in a loop until budget is exhausted.
+- **Schema-validation failures retried verbatim** — wasting tokens on a call the validator will keep rejecting.
+- **Stale-worker / stale-lock states** — no retry can resolve a worker that died holding a lock; the loop just spins.
+- **Worktree-invalidity errors** — recovery can't fix without operator intervention; retrying writes to a broken root.
+
+A retry without a class is a guess; a guess at scale is a budget leak.
+
+## The Classification Taxonomy
+
+Six classes. Each maps to one intentional action:
+
+| Class | Signal | Action |
+|---|---|---|
+| **provider** | API timeout, 5xx, rate limit, network, transient cloud error | retry with exponential backoff |
+| **tool-schema** | tool input rejected by validator, missing required field, type mismatch | repair input, do **not** retry verbatim |
+| **deterministic-policy** | gateguard / write-gate / permission denied / explicit policy block | pause, ask operator (do **not** retry) |
+| **git** | merge conflict, detached HEAD, unmerged paths, lockfile, pre-commit hook | self-heal if known recipe, else pause |
+| **worktree** | missing `.git`, invalid root, lease lost, prunable worktree, foreign session | stop — never spawn workers into unresolved paths |
+| **runtime** | OOM, segfault, host kill, parent process gone, context exhaustion | stop, surface to operator |
+
+A failure that fits no class is `unclassified` — that itself is a signal: the taxonomy is incomplete and needs a new entry, not a retry.
+
+## The Output Contract
+
+Before any retry, emit one fenced block:
+
+```
+recovery-classification:
+  failure:        <one-line summary>
+  class:          tool-schema
+  evidence:       stderr line 14: "missing required field: workspace_id"
+  action:         repair input (add workspace_id from session context), do NOT retry verbatim
+  retry budget:   2/3 remaining (this class)
+```
+
+Retry budgets are **per-class**, not global. A failed class that resolves on retry resets its budget; a class that exhausts its budget escalates to `pause` regardless of remaining global retries. This keeps a flaky network from masking a persistent schema bug.
+
+## Anti-Patterns
+
+- **One retry budget for all classes.** A network blip and a schema mismatch consume the same counter, so persistent schema bugs masquerade as "flaky network."
+- **Auto-retry on `deterministic-policy`.** The gate exists exactly because retry is wrong. Pause instead and surface the policy that fired.
+- **Classifying after retry.** The class informs the action; classifying afterward turns it into a post-mortem label and the loop has already misspent its budget.
+- **Coalescing `worktree` into `git`.** Worktree errors are stop-class; git errors are usually self-heal-class. Conflating them lets workers spawn into broken roots.
+- **Treating `unclassified` as `provider`.** Unknown is not transient. Force a taxonomy update; do not paper over the gap with a backoff.
+
+## Pairs With
+
+- [verification-loop](verification-loop.md) — every Phase 1–6 failure routes through here before any retry.
+- [state-reconciliation](state-reconciliation.md) — runs before the next loop iteration when class is `git` or `runtime`, since those classes often leave drift behind.
+- [worktree-safety](worktree-safety.md) — class `worktree` is exactly worktree-safety's failure surface; the two are co-defined.
+- [gateguard](gateguard.md) — class `deterministic-policy` is gateguard's surface; recovery-classification names what gateguard already blocked.