# Artifacts Source: https://recursive-mode.dev/concepts/artifacts What artifact files are, how the draft-to-lock lifecycle works, and how to read them. An **artifact** is a Markdown file that records the inputs, outputs, reasoning, and evidence for a single phase of a single run. Every phase produces exactly one artifact. Artifacts are locked when complete and never edited afterward — corrections flow forward through addenda. The artifact for run `75`, Phase 1 lives at: ```text theme={null} /.recursive/run/75/01-as-is.md ``` All artifacts for a run live together under `/.recursive/run//`. *** ## Required header Every artifact begins with a standard header block that records the run, phase, status, inputs, outputs, and scope: ```markdown artifact header theme={null} Run: `/.recursive/run//` Phase: `01 AS-IS analysis` Status: `DRAFT` Inputs: - `/.recursive/run//00-requirements.md` - `/.recursive/run//00-worktree.md` Outputs: - `/.recursive/run//01-as-is.md` Scope note: This artifact analyzes the current codebase state as it relates to the in-scope requirements. It is the input to Phase 2 planning. ``` ```markdown locked artifact header theme={null} Run: `/.recursive/run//` Phase: `01 AS-IS analysis` Status: `LOCKED` Inputs: - `/.recursive/run//00-requirements.md` - `/.recursive/run//00-worktree.md` Outputs: - `/.recursive/run//01-as-is.md` Scope note: This artifact analyzes the current codebase state as it relates to the in-scope requirements. It is the input to Phase 2 planning. LockedAt: `2025-11-14T09:22:31Z` LockHash: `a3f8c2d14e67b09f5c1843a2e9d07f6b3281cc4d90e5f1a87b2344c6d8e0f912` ``` The `Inputs` list must include every file the phase read to produce its output — base input files and any applicable addenda, in lexical order. *** ## Draft-to-lock lifecycle Audited phases follow a mandatory loop before they can lock: Write the phase artifact from the effective inputs. Record `Status: DRAFT` in the header. Re-read the upstream artifacts, reconcile against the diff basis in `00-worktree.md`, and run the phase audit. Record the audit result in `## Audit Verdict`. If the audit finds gaps or drift, fix the work. Stay in the current phase — do not advance. Run the audit again with the repaired artifact as input. Only after `Audit: PASS` may you set `Coverage: PASS` and `Approval: PASS` in the gates. Run `recursive-lock` to write `Status: LOCKED`, `LockedAt`, and `LockHash` into the artifact header. The artifact is now immutable. Do not set `Coverage: PASS` or `Approval: PASS` unless `Audit: PASS` has already been recorded. Do not advance to the next phase while any required gate reads `FAIL`. Non-audited phases (Phase 0 worktree, Phase 0 requirements, Phase 5) follow the same draft-and-lock pattern but without the mandatory audit loop. *** ## Coverage Gate and Approval Gate Every artifact (except `00-requirements.md`) must end with both gates before locking. **Coverage Gate** — proves the output addresses everything relevant in the input, including addenda: ```markdown theme={null} ## Coverage Gate - Effective inputs reviewed: - `/.recursive/run//00-requirements.md` - `/.recursive/run//addenda/01-as-is-addendum-001.md` - Requirement coverage check: - `R1`: Covered at ## Current authentication flow - `R2`: Covered at ## Token storage analysis - `R3`: Deferred — out of scope for this run - Out-of-scope confirmation: - `OOS1`: unchanged Coverage: PASS ``` **Approval Gate** — proves the artifact is ready for the next phase: ```markdown theme={null} ## Approval Gate - Objective readiness checks: - Artifact is internally consistent - All in-scope requirements have explicit dispositions - No required section is missing - Remaining blockers: - none Approval: PASS ``` If either gate cannot pass, set it to `FAIL` and list the exact fixes required before proceeding. *** ## Addenda An **addendum** is a correction or extension attached to the *current* phase when a later phase discovers a gap in an earlier locked phase. You never edit the locked artifact — you create an addendum file under `/.recursive/run//addenda/` that carries the correction forward. Addenda are treated as authoritative effective inputs. Any artifact that relies on an addendum must list it in its `Inputs` field and reconcile it explicitly in the artifact body. Two types of addenda exist: * **Stage-local addendum** — corrects or extends the current phase's own understanding without touching locked history. * **Upstream-gap addendum** — compensates for a gap in a prior locked phase, applied at the current phase instead of rewriting the past. When you need to correct something a prior phase got wrong, don't try to unlock and edit it. Create an upstream-gap addendum in the current phase and reconcile the correction there. *** ## Lock fields When an artifact locks, three fields are appended to the header: ```markdown lock block theme={null} Status: `LOCKED` LockedAt: `2025-11-14T09:22:31Z` LockHash: `a3f8c2d14e67b09f5c1843a2e9d07f6b3281cc4d90e5f1a87b2344c6d8e0f912` ``` ```bash locking command theme={null} # Use recursive-lock to write the lock fields correctly python scripts/recursive-lock.py --run-id 75 --phase 01 pwsh -NoProfile -File scripts/recursive-lock.ps1 -RunId 75 -Phase 01 ``` `LockHash` is a SHA-256 of the artifact content at the moment of locking. Use `verify-locks` to confirm that no artifact has been modified after locking: ```bash theme={null} python scripts/verify-locks.py --run-id 75 pwsh -NoProfile -File scripts/verify-locks.ps1 -RunId 75 ``` Always use `recursive-lock` to write lock fields. Do not hand-write `Status: LOCKED` or compute `LockHash` manually — the script ensures consistency with what `verify-locks` expects. # Memory Source: https://recursive-mode.dev/concepts/memory The durable memory plane — what it stores, how it's organized, and when to read and update it. recursive-mode maintains a **memory plane** separate from run artifacts and control-plane docs. Memory stores project knowledge that is worth keeping across runs — domain context, reusable patterns, recurring failure modes, and capability guidance. It is intentionally distinct from the current repository state and from run-specific evidence. Read `/.recursive/memory/MEMORY.md` at the start of every new session and at the start of every new run. `MEMORY.md` is the router and index for the entire memory plane — start there, then load only the memory docs relevant to your current task. *** ## What memory is for Memory answers a different question than `STATE.md` or `DECISIONS.md`: | Document | Question it answers | | -------------------------- | ----------------------------------------------------------- | | `/.recursive/STATE.md` | What is true in the codebase right now? | | `/.recursive/DECISIONS.md` | What decisions were made and why? | | `/.recursive/memory/` | What has been learned that's worth remembering across runs? | Use memory to store things that have proven durable — a recurring architectural pattern, a subsystem that frequently causes regressions, a lesson that surfaced in multiple runs. Do not use memory as a dump for session noise or one-off observations that have not been validated. *** ## Memory directory layout The router and index for the entire memory plane. It records the memory taxonomy, retrieval guide, freshness policy, sharding rules, and an ownership map of which memory docs cover which paths. Read this first — do not load the full memory tree without reading `MEMORY.md` first. Domain memory docs capture durable knowledge about specific areas of the codebase — architecture, data flows, subsystem boundaries, and ownership. Each domain doc declares `Owns-Paths` (the code surfaces it is authoritative for) and `Watch-Paths` (paths it monitors for relevant changes). Pattern docs record reusable implementation patterns that have proven effective in this repository. They declare `Watch-Paths` without owning the paths outright. Use patterns docs for things like "the standard way to add a new API endpoint" or "the approved error-handling strategy." Incident docs record recurring failure modes, past regressions, and known problem areas. When a pattern of failure is strong enough to be worth remembering, it belongs here so future runs can check for it proactively. Episode docs capture significant run histories or cross-run narratives — for example, a multi-run migration, a refactor that unfolded over several tasks, or a platform-specific investigation that took multiple iterations to resolve. Skills memory is a first-class part of the memory plane. `SKILLS.md` is the skill-memory router. Durable skill knowledge is sharded under four subdirectories: * `availability/` — environment-specific capability probes and availability notes * `usage/` — stable skill fit and usage guidance * `issues/` — recurring skill failures or confusing behavior * `patterns/` — reusable multi-skill operating patterns Load `SKILLS.md` and relevant skill shards when a run involves delegated review, subagent help, review bundles, or other capability-sensitive execution. Deprecated memory docs that have been superseded or are no longer relevant. Archived docs are excluded from normal retrieval and kept only for historical reference. *** ## Memory status values Every durable memory doc (except `MEMORY.md` and `SKILLS.md`) carries a `Status` field: | Status | Meaning | Used in retrieval? | | ------------ | ---------------------------------------------------------- | ------------------ | | `CURRENT` | Authoritative for planning and execution | Yes | | `SUSPECT` | May be used as a lead but must be revalidated before trust | Yes, with caution | | `STALE` | Outdated; excluded from default retrieval | No | | `DEPRECATED` | Historical only; excluded from default retrieval | No | | `DRAFT` | Candidate memory, not yet durable | No | Prefer `CURRENT` docs for all planning and execution. Use `SUSPECT` docs only as leads — revalidate them before acting on them. *** ## When to read memory Read `/.recursive/STATE.md`, `/.recursive/DECISIONS.md`, and `/.recursive/memory/MEMORY.md` before doing any work. These three docs orient you to the current state of the repo and the accumulated knowledge from prior runs. Re-read all three before creating or updating run artifacts. Then use `DECISIONS.md` to identify any earlier runs relevant to the current requirement or subsystem. After reading `MEMORY.md`, load only the memory docs relevant to the current task. Do not load the entire memory tree by default. If the run involves delegated review, subagent help, review bundles, or other capability-sensitive execution, load `/.recursive/memory/skills/SKILLS.md` and the relevant skill shards before planning or auditing. *** ## When memory is updated Memory is updated in **Phase 8** at run closeout. Phase 8: 1. Reviews which memory docs have `Owns-Paths` or `Watch-Paths` that overlap with the validated diff. 2. Downgrades any `CURRENT` docs touched by the diff to `SUSPECT` until semantic review against the final code, `STATE.md`, and `DECISIONS.md` is complete. 3. Promotes durable lessons from the run into the appropriate memory subdirectory. 4. Creates a new domain doc (or records a follow-up) for any changed code paths not covered by an existing domain doc. 5. Records a run-local skill usage capture and decides what, if anything, is worth promoting into `/.recursive/memory/skills/`. Phase 8 produces `08-memory-impact.md` as a compact delta receipt pointing to the updated memory docs. *** ## Skills memory Phase 8 must update skill memory when a run teaches the repository something durable about: * skill availability in this environment * skill fit for a specific type of task * delegated review quality * repeated workflow friction with a skill Record skill discoveries in `/.recursive/memory/skills/` so future runs don't have to rediscover whether a subskill is available or how well it fits a particular task pattern. *** ## Memory freshness rules Every durable memory doc includes metadata fields that support freshness tracking: ```markdown theme={null} Type: `domain` Status: `CURRENT` Scope: `Authentication subsystem` Owns-Paths: - `src/auth/**` Watch-Paths: - `src/middleware/session.ts` Source-Runs: - `/.recursive/run/42/` Validated-At-Commit: `a1b2c3d4` Last-Validated: `2025-10-01T14:00:00Z` Tags: - `auth` - `session` ``` If the final validated diff of a run touches a path matched by `Owns-Paths` or `Watch-Paths`, that memory doc must be reviewed in Phase 8. A doc stays `SUSPECT` until the reviewing agent has checked it against the final code, `STATE.md`, and `DECISIONS.md` and confirmed it is still accurate. # Phases Source: https://recursive-mode.dev/concepts/phases Detailed reference for every phase in a Recursive Mode run — purpose, artifact file, and audit requirements. A run moves through phases in order. Each phase reads the previous phase's locked artifact as its primary input and produces its own artifact before the next phase can begin. You cannot skip phases or edit a locked artifact — corrections flow forward through addenda. ## Phase reference | Phase | Name | Artifact file | Audited | | ----- | ------------------------------ | ------------------------------ | ------------------------ | | 0 | Worktree setup | `00-worktree.md` | No | | 0 | Requirements | `00-requirements.md` | No | | 1 | AS-IS analysis | `01-as-is.md` | Yes | | 1.5 | Root cause *(debug runs only)* | `01.5-root-cause.md` | Yes | | 2 | TO-BE plan | `02-to-be-plan.md` | Yes | | 3 | Implementation | `03-implementation-summary.md` | Yes | | 3.5 | Code review *(optional)* | `03.5-code-review.md` | Yes | | 4 | Test summary | `04-test-summary.md` | Yes | | 5 | Manual QA | `05-manual-qa.md` | No (gate varies by mode) | | 6 | Decisions update | `06-decisions-update.md` | Yes | | 7 | State update | `07-state-update.md` | Yes | | 8 | Memory impact | `08-memory-impact.md` | Yes | All artifacts live under `/.recursive/run//`. *** ## Phase 0 — Worktree setup **Artifact:** `/.recursive/run//00-worktree.md` Phase 0 (worktree) creates an isolated git worktree at `.worktrees//` so all implementation work happens off the main branch. It records the diff basis that every later audited phase uses for reconciliation — baseline type, baseline reference, comparison reference, and the normalized diff command. It also verifies the project builds and all tests pass before any changes are made. Never implement changes on main or master without explicit consent. Phase 0 exists to prevent this. `00-worktree.md` must lock before Phase 1 begins. All subsequent phases execute inside the worktree context. *** ## Phase 0 — Requirements **Artifact:** `/.recursive/run//00-requirements.md` The requirements artifact is the only phase input that comes from outside the run folder — you create it from your task description, issue tracker, or planning document before starting the run. It defines the in-scope requirements (`R1`, `R2`, …) that every downstream phase must address. Keep requirements in the file, not in prompts. Prompts should reference the file path, not duplicate its content. *** ## Phase 1 — AS-IS analysis **Artifact:** `/.recursive/run//01-as-is.md` Phase 1 reads the requirements and produces a grounded analysis of the current codebase state as it relates to those requirements. The audit must re-read any earlier run artifacts relevant to the same subsystem or architectural area, record which upstream artifacts were reviewed, and confirm the analysis reflects what is actually true in the repo — not what was previously assumed. *** ## Phase 1.5 — Root cause *(debug runs only)* **Artifact:** `/.recursive/run//01.5-root-cause.md` Use Phase 1.5 when the requirement involves debugging a bug, test failure, or unexpected behavior. It reads `01-as-is.md` and produces a root cause analysis before any fix is planned. Do not write or plan a fix before Phase 1.5 is locked. The audit must confirm the root cause — not just the symptom — and must fail if the fix strategy is still guesswork. Phase 1.5 is optional. When present, it must lock before Phase 2 begins, and Phase 2 takes `01.5-root-cause.md` as an additional input. *** ## Phase 2 — TO-BE plan **Artifact:** `/.recursive/run//02-to-be-plan.md` Phase 2 produces an ExecPlan-grade implementation plan based on the AS-IS analysis (and root cause, when present). The audit fails unless every in-scope requirement is planned, targeted files and modules are concrete, and tests and QA coverage are specific enough for later diff reconciliation. Phase 2 owns planned scope only. If a later phase discovers that the real diff surface differs from what was planned, that drift is reconciled in Phase 3 — not by retroactively editing Phase 2. *** ## Phase 3 — Implementation **Artifact:** `/.recursive/run//03-implementation-summary.md` Phase 3 executes the plan. It must declare a TDD mode: * **Strict** (default) — requires explicit RED and GREEN evidence paths under `/.recursive/run//evidence/`. * **Pragmatic** — requires an explicit exception rationale plus compensating validation evidence. The audit reconciles the requirements, the plan, actual changed files against claimed scope, and required implementation and test evidence. All implementation work happens inside the isolated worktree. *** ## Phase 3.5 — Code review *(optional)* **Artifact:** `/.recursive/run//03.5-code-review.md` Use Phase 3.5 for high-risk changes, complex multi-agent sub-phases, or when extra confidence is needed before testing. When present, it must lock before Phase 4. Delegated review is valid only when accompanied by a full context bundle stored under `/.recursive/run//evidence/review-bundles/`. If blocking issues are found, Phase 3.5 fails and the run returns to Phase 3 for repair. *** ## Phase 4 — Test summary **Artifact:** `/.recursive/run//04-test-summary.md` Phase 4 runs the test suite and records results. Before running tests, it performs a pre-test implementation audit against requirements, plan, current diff ownership, and required test files. If that audit finds unfinished in-scope work, the run returns to Phase 3 before relying on test results. *** ## Phase 5 — Manual QA **Artifact:** `/.recursive/run//05-manual-qa.md` Phase 5 validates the implemented system against the QA scenarios defined in `02-to-be-plan.md`. You must declare a QA execution mode: | Mode | Sign-off required | Execution record required | | ---------------- | ----------------- | ------------------------- | | `human` | Yes (user) | No | | `agent-operated` | No | Yes | | `hybrid` | Yes (user) | Yes | Human and hybrid modes pause and wait for your explicit sign-off before proceeding to closeout. *** ## Phase 6 — Decisions update **Artifact:** `/.recursive/run//06-decisions-update.md` Phase 6 appends a new entry to `/.recursive/DECISIONS.md` — the global decision ledger — documenting what changed and why. The phase artifact is a compact delta receipt that points to the ledger entry; it does not duplicate `DECISIONS.md` content. The audit verifies the ledger entry matches the run folder, reviewed diff-owned paths, and validated outcomes. *** ## Phase 7 — State update **Artifact:** `/.recursive/run//07-state-update.md` Phase 7 updates `/.recursive/STATE.md` to reflect what is true in the codebase now. The phase artifact is a compact delta receipt summarizing what changed in the state doc. `STATE.md` must reflect what is actually true — not what was intended. The audit verifies this against the validated diff and final codebase state. *** ## Phase 8 — Memory impact **Artifact:** `/.recursive/run//08-memory-impact.md` Phase 8 reviews the memory plane under `/.recursive/memory/` and updates it based on what the run taught the repository. It records a run-local skill usage capture, reviews affected memory docs for freshness, and promotes durable lessons into the appropriate memory subdirectory. Any memory doc whose `Owns-Paths` or `Watch-Paths` overlap with the validated diff must be reviewed. `CURRENT` docs touched by the diff are downgraded to `SUSPECT` until semantic review against final code, `STATE.md`, and `DECISIONS.md` is complete. See [Memory](/concepts/memory) for the full memory model. # Workflow overview Source: https://recursive-mode.dev/concepts/workflow-overview The big picture of how recursive-mode works — runs, phases, artifacts, and feedback loops. ## The problem: context rot When you work with an AI agent over many sessions, important decisions, requirements, and implementation rationale accumulate in chat history — and then disappear. The agent rediscovers the same facts, makes contradictory choices, and loses track of what was actually agreed. This is context rot. recursive-mode solves context rot by moving the source of truth out of chat and into repository files. Requirements live in a file. Plans live in a file. Implementation evidence lives in a file. The agent reads those files at the start of every run; it does not rely on remembering what was discussed. ## Prompts are commands, not specs In recursive-mode, prompts stay short and command-like: ```text theme={null} Implement the run Implement run 75 Start a recursive run ``` The actual requirements, acceptance criteria, and plan live in repo documents. The prompt tells the agent *which phase to run* and *which files to use* — nothing more. This means you can hand off a run to a different agent, resume after a week, or add a contributor without re-explaining everything in chat. ## The run model Every task is a **run**. Each run gets its own folder: ```text theme={null} /.recursive/run// ``` That folder is the durable record for the task. It contains every phase artifact, any addenda, and all evidence. You can read it, audit it, and resume it at any time without depending on chat history. ## Phase progression A run moves through a fixed sequence of phases. Each phase consumes the previous phase's output as input and produces its own locked artifact before the next phase can begin. ```mermaid theme={null} flowchart TD P0R["Phase 0 — Requirements\n00-requirements.md"] P0W["Phase 0 — Worktree setup\n00-worktree.md"] P1["Phase 1 — AS-IS analysis\n01-as-is.md"] P15["Phase 1.5 — Root cause\n01.5-root-cause.md\n(debug runs only)"] P2["Phase 2 — TO-BE plan\n02-to-be-plan.md"] P3["Phase 3 — Implementation\n03-implementation-summary.md"] P35["Phase 3.5 — Code review\n03.5-code-review.md\n(optional)"] P4["Phase 4 — Test summary\n04-test-summary.md"] P5["Phase 5 — Manual QA\n05-manual-qa.md"] P6["Phase 6 — Decisions update\n06-decisions-update.md"] P7["Phase 7 — State update\n07-state-update.md"] P8["Phase 8 — Memory impact\n08-memory-impact.md"] LOCK["Artifacts locked\nHistory preserved"] P0R --> P0W --> P1 P1 -.->|debug runs| P15 P15 --> P2 P1 --> P2 P2 --> P3 P3 -.->|optional| P35 P35 --> P4 P3 --> P4 P4 --> P5 P5 --> P6 --> P7 --> P8 --> LOCK ``` Phases are one-way. Once a phase locks, the agent cannot edit its artifact. If a later phase discovers a gap in an earlier phase, it records an **addendum** — a correction file attached to the current phase — rather than rewriting the locked past. ## Audited phases and gates Most phases are **audited**. An audited phase must complete a full `draft → audit → repair → re-audit → pass → lock` loop before advancing. No phase can declare itself done by assertion alone. Every phase output must end with two explicit gates: * **Coverage Gate** — proves the output addresses everything relevant in the input, including any addenda. * **Approval Gate** — proves the output is ready to proceed to the next phase. Neither gate can be set to `PASS` unless the audit has already passed. ## The feedback loop The real power of the workflow is what happens at closeout. Phases 6, 7, and 8 feed validated outcomes back into the shared control plane: | Phase | Updates | | ------- | ----------------------------------------------------------------------- | | Phase 6 | `/.recursive/DECISIONS.md` — the global decision ledger | | Phase 7 | `/.recursive/STATE.md` — the current state of the codebase | | Phase 8 | `/.recursive/memory/` — durable domain knowledge, patterns, and lessons | The next run starts by reading all three. This means each run benefits from the validated conclusions of every previous run — requirements are understood faster, analysis is more accurate, and the agent avoids repeating past mistakes. ## Key guardrails These guardrails are non-negotiable. They exist to keep the workflow auditable and the history trustworthy. * **Repo documents are the source of truth.** The agent reads phase input files from disk at the start of each phase. Conversational context cannot carry requirements. * **Phases are one-way.** After a phase locks, its artifact is not edited. Use addenda for corrections. * **Locked history is not rewritten.** All corrections flow forward through addenda and downstream reconciliation. * **Gates are mandatory.** Every phase artifact must end with `Coverage: PASS` and `Approval: PASS` — and both require a prior `Audit: PASS`. * **Delegated work is not trusted without verification.** When subagents contribute, the main agent verifies their claims against real files, diffs, and artifacts before accepting. # Auditing Phases Source: https://recursive-mode.dev/guides/auditing-phases How the audit loop works and what you need to know about phase gates, addenda, and requirement tracking. recursive-mode enforces an audit loop on every major phase. A phase cannot lock — and the next phase cannot start — until the audit passes. This prevents vague "done" claims from advancing through the workflow. ## The audit lifecycle Every audited phase follows this sequence: ```text theme={null} draft → audit → repair → re-audit → pass → lock ``` The agent cannot set `Coverage: PASS` or `Approval: PASS` for an audited phase unless the artifact ends with `Audit: PASS`. The agent cannot lock the artifact unless both gates pass. There are no shortcuts. ## Which phases require auditing | Phase | Artifact | | ----------------------------------- | ------------------------------ | | Phase 1 — AS-IS | `01-as-is.md` | | Phase 1.5 — Root Cause (debug mode) | `01.5-root-cause.md` | | Phase 2 — TO-BE plan | `02-to-be-plan.md` | | Phase 3 — Implementation summary | `03-implementation-summary.md` | | Phase 3.5 — Code review | `03.5-code-review.md` | | Phase 4 — Test summary | `04-test-summary.md` | | Phase 6 — Decisions update | `06-decisions-update.md` | | Phase 7 — State update | `07-state-update.md` | | Phase 8 — Memory impact | `08-memory-impact.md` | ## Coverage Gate and Approval Gate Every audited phase ends with two mandatory gates: **Coverage Gate** — proves the artifact addresses everything relevant in its inputs, including any applicable addenda. The agent must demonstrate that nothing was silently skipped. **Approval Gate** — proves the artifact is actually ready to proceed to the next phase. For Phase 5 (manual QA), human or hybrid modes require explicit user sign-off before this gate can pass. Both gates must pass before the artifact can lock. A phase that locks without both gates is a workflow violation. ## Addenda Locked artifacts must not be edited. If a later phase discovers a gap, an error, or missing information in an earlier locked phase, you use an **addendum** instead. Addenda live at: ```text theme={null} /.recursive/run//addenda/ ``` An addendum is an authoritative effective input. The agent must: 1. List relevant addenda under `Inputs` in the current phase artifact 2. Re-read them as part of `## Effective Inputs Re-read` 3. Explicitly reconcile them in `## Earlier Phase Reconciliation` Addenda are automatically included when generating review bundles for delegated review. Do not omit them from any delegated context. ## Requirement Completion Status Every audited phase must include a `## Requirement Completion Status` section that accounts for every in-scope requirement (`R#`). Each requirement needs an explicit disposition: | Disposition | Meaning | What's required | | -------------- | ---------------------------------------------------- | ---------------------------------------------------------------- | | `implemented` | Code was written to satisfy this requirement | Must cite `Changed Files` | | `verified` | This requirement was validated, not just implemented | Must cite `Changed Files` **and** distinct verification evidence | | `deferred` | Intentionally postponed | Must cite `Deferred By` and rationale | | `out-of-scope` | Not part of this run | Must cite `Scope Decision` | You cannot mark a requirement as `implemented` or `verified` without concrete `Changed Files`. You cannot mark `verified` without separate verification evidence — citing the same code that implements the requirement is not sufficient. ## Locking an artifact After `Audit: PASS`, `Coverage: PASS`, and `Approval: PASS`, lock the artifact using the `recursive-lock` script: ```bash theme={null} python scripts/recursive-lock.py --repo-root . --run-id --phase 02 ``` The script writes `Status: LOCKED`, `LockedAt`, and `LockHash` to the artifact. Do not manually edit those fields — a manual edit will produce a LockHash mismatch that the verify script will catch. To verify all locks in a run: ```bash theme={null} python scripts/verify-locks.py --repo-root . --run-id ``` # Delegated Review Source: https://recursive-mode.dev/guides/delegated-review How to set up and use delegated code review and phase audits with subagents. recursive-mode supports delegating audits and code reviews to subagents. When configured correctly, a subagent receives a complete context bundle, returns grounded findings and a verdict, and the main agent verifies that result before accepting it. Delegated review is optional. If subagents are unavailable, the main agent performs the same audit as a self-audit. Audit rigor is not optional — only delegation is. ## When to use delegated review * Phase 3.5 code review — the primary use case * Any audited phase where an independent pass would improve quality * High-risk or large-scale implementations where a second opinion on requirement coverage matters ## How it works Use the `recursive-review-bundle` script to package everything the reviewer needs into a canonical, reproducible bundle: ```bash Python theme={null} python scripts/recursive-review-bundle.py \ --repo-root . \ --run-id "" \ --phase "03.5 Code Review" \ --role code-reviewer \ --artifact-path "/.recursive/run//03.5-code-review.md" \ --upstream-artifact "/.recursive/run//00-requirements.md" \ --upstream-artifact "/.recursive/run//02-to-be-plan.md" \ --audit-question "Which R# remain incomplete?" \ --required-output "Findings ordered by severity" ``` ```powershell PowerShell theme={null} pwsh -NoProfile -File scripts/recursive-review-bundle.ps1 ` -RepoRoot . ` -RunId "" ` -Phase "03.5 Code Review" ` -Role code-reviewer ` -ArtifactPath "/.recursive/run//03.5-code-review.md" ` -UpstreamArtifact "/.recursive/run//00-requirements.md","/.recursive/run//02-to-be-plan.md" ` -AuditQuestion "Which R# remain incomplete?" ` -RequiredOutput "Findings ordered by severity" ``` The bundle is saved under `/.recursive/run//evidence/review-bundles/`. The bundle auto-discovers relevant addenda — do not omit them from the delegated context. Dispatch the subagent with the bundle path and the phase-specific instructions. Valid subagent roles include: * `phase-auditor` — independent pass over draft, upstream artifacts, diff, and requirement coverage * `code-reviewer` — Phase 3.5; checks requirements vs implementation, plan vs implementation, and code quality * `traceability-auditor` — verifies every in-scope `R#` is explicitly addressed * `test-reviewer` — verifies test adequacy, exact commands, and evidence capture * `memory-auditor` — Phase 8; verifies memory status transitions and router updates Vague delegation ("review this phase") is not valid. The subagent must receive a complete context bundle. The subagent must return structured findings and one of: * `Audit: PASS` — the phase is ready to lock * `Audit: FAIL` — repairs are needed before the phase can proceed A result that contains only generic praise with no grounded findings, or that lacks an explicit verdict, must be rejected. Before accepting a delegated result, the main agent must verify the subagent's claims against: * the actual worktree diff * the actual changed files * the actual phase artifacts and review bundle If the verification reveals issues, record the concrete repair performed. Do not silently accept stale delegated context. Every meaningful subagent contribution must produce a durable action record under: ```text theme={null} /.recursive/run//subagents/ ``` The action record captures inputs provided, claimed actions, claimed file and artifact impact, findings, and the acceptance decision. The Phase 3.5 artifact must also record `Review Bundle Path` in `## Review Metadata`. Never accept a delegated result without verifying the subagent's claims against actual files, the actual diff, and the actual recursive artifacts. A subagent's word is not sufficient — the main agent is always responsible for verification before lock. ## Self-audit fallback When subagents are unavailable, perform the same audit locally and record it in the phase artifact: ```text theme={null} Audit Execution Mode: self-audit Subagent Availability: unavailable ``` Then complete the full audit loop — draft, re-read upstream artifacts, reconcile against the diff basis, record gaps, repair, re-audit, and set `Audit: PASS` only when the phase is genuinely ready. Self-audit must meet the same standard as delegated audit. ## What makes a valid review bundle A bundle is only valid when it includes all of the following: * Phase name and artifact path * Artifact content hash * Reviewer role * Upstream artifacts to re-read * Relevant addenda * Relevant prior recursive evidence * Normalized diff basis from `00-worktree.md` * Changed file list * Targeted code references * Phase-specific audit questions * Required output shape (findings format and verdict) If any item is missing, do not delegate — run the audit yourself. # Starting a Run Source: https://recursive-mode.dev/guides/starting-a-run How to start and resume Recursive Mode runs. Once your repo is bootstrapped and your requirements live in a repository file, you can start or resume work with a short command. Prompts are commands — not specifications. The actual requirements and plan must always live in repo documents. Keep your prompts short and command-like. Place requirements, acceptance criteria, and implementation plans in repository documents and reference those paths in your prompt. Do not paste specifications into the chat. ## Starting a new run The `/.recursive/` scaffold must exist before any run can begin. If it's missing, run the bootstrap installer: ```bash theme={null} python scripts/install-recursive-mode.py --repo-root . ``` The scaffold includes `/.recursive/RECURSIVE.md`, `/.recursive/STATE.md`, `/.recursive/DECISIONS.md`, the memory plane under `/.recursive/memory/`, and the run root at `/.recursive/run/`. Write your requirements in a file inside the repository — for example, a requirements doc or a planned feature spec. Do not paste requirements into the prompt. The agent will read from that file. Trigger the agent with a command like one of these: ```text theme={null} Implement the run Implement run 75 Implement the plan Start a recursive run Create a new run based on the plan ``` The agent reads `/.recursive/RECURSIVE.md`, `/.recursive/STATE.md`, `/.recursive/DECISIONS.md`, and the relevant memory docs before proceeding. A new run folder is created at: ```text theme={null} /.recursive/run// ``` This folder becomes the durable record for the entire run. Every phase artifact is written here. The agent starts with Phase 0 (worktree setup in `00-worktree.md`), then moves through: * Phase 0 — Requirements (`00-requirements.md`) * Phase 1 — AS-IS analysis (`01-as-is.md`) * Phase 2 — TO-BE plan (`02-to-be-plan.md`) * Phase 3 — Implementation (`03-implementation-summary.md`) * Phase 3.5 — Code review (`03.5-code-review.md`) * Phase 4 — Tests (`04-test-summary.md`) * Phase 5 — Manual QA (`05-manual-qa.md`) * Phases 6–8 — Decisions, state, and memory closeout ## Resuming a run If a run is interrupted — by session end, context limits, or a manual pause — you can resume it: | Situation | Command | | ------------------------------------------- | ----------------------------------------------------------- | | Exactly one active or incomplete run exists | `Implement the run` | | Multiple runs exist | `Implement run 75` | | Resuming from a specific plan artifact | `Implement the plan at /.recursive/run/75/02-to-be-plan.md` | The agent re-reads `/.recursive/STATE.md`, `/.recursive/DECISIONS.md`, and `/.recursive/memory/MEMORY.md` at the start of every resumed session to rebuild context from the repo, not from chat history. ## Command interpretation rules The agent resolves ambiguous commands using these rules: * **Explicit run ID** — use that run * **No run ID + one active run** — resume it * **Reference to a plan** — create a new run only when a unique source plan or requirements artifact can be identified from repo docs * **Ambiguous** — the agent asks you for the run ID or the exact repo path to the plan or requirements artifact If you ever need to check which runs are active: ```bash theme={null} python scripts/recursive-status.py --repo-root . ``` # Troubleshooting Source: https://recursive-mode.dev/guides/troubleshooting Common issues when running recursive-mode and how to resolve them. The agent must read the three core control-plane docs at the start of every new session: * `/.recursive/STATE.md` — current state of the repo and codebase * `/.recursive/DECISIONS.md` — prior work and the reasoning behind it * `/.recursive/memory/MEMORY.md` — memory router, taxonomy, and freshness policy If the repo is not bootstrapped, or those files are missing or stale, run the bootstrap installer: ```bash theme={null} python scripts/install-recursive-mode.py --repo-root . ``` Ensure your agent environment loads `SKILL.md` (the installable skill entrypoint) so it knows to read those files at session start. Locked artifacts must not be edited. Once a phase locks, its artifact is immutable. If a later phase discovers a gap, an error, or missing information in an earlier locked phase, use an **addendum** instead: ```text theme={null} /.recursive/run//addenda/ ``` Addenda are authoritative effective inputs. The current phase must list them under `Inputs`, re-read them, and reconcile them explicitly. They do not rewrite locked history — they extend it. The audit loop must complete in full before a phase can lock. The required sequence is: ```text theme={null} draft → audit → repair → re-audit → pass → lock ``` `Coverage: PASS` and `Approval: PASS` cannot be set until `Audit: PASS` appears at the end of the artifact. Check the artifact for any outstanding gaps, drift from the diff basis, or incomplete `Requirement Completion Status` entries, and complete another audit cycle. Do not manually edit `Status`, `LockedAt`, or `LockHash` fields. Those fields must be written by the `recursive-lock` script, which computes the correct SHA-256 hash of the artifact content: ```bash theme={null} python scripts/recursive-lock.py --repo-root . --run-id --phase 02 ``` If the fields were edited by hand, re-lock using the script. Verify all locks in the run with: ```bash theme={null} python scripts/verify-locks.py --repo-root . --run-id ``` This is a TDD violation. If you are using `recursive-tdd` in strict mode, the RED phase (a failing test) must be completed and recorded before any implementation code is written. To fix it: 1. Delete the implementation code 2. Write a failing test that targets the intended behavior 3. Record the RED evidence in the phase artifact 4. Re-implement to make the test pass (GREEN phase) If strict TDD is not appropriate for the situation, declare `TDD Mode: pragmatic` in the Phase 3 artifact and record an explicit exception rationale along with compensating evidence. Create an addendum file in the run's addenda directory: ```text theme={null} /.recursive/run//addenda/ ``` Name it descriptively and write the correction or clarification there. The current phase and all downstream phases treat addenda as authoritative effective inputs. List the addendum under `Inputs` in the current phase artifact, re-read it, and reconcile it explicitly. Do not edit the locked artifact — a LockHash mismatch will be detected by `verify-locks`. The repo has not been bootstrapped yet. Run the installer for your toolchain: ```bash theme={null} python scripts/install-recursive-mode.py --repo-root . ``` ```bash theme={null} bash scripts/install-recursive-mode.sh --repo-root . ``` ```powershell theme={null} pwsh -NoProfile -File scripts/install-recursive-mode.ps1 -RepoRoot . ``` This creates the `/.recursive/` scaffold, bridge docs, memory routers, and the run layout the workflow depends on. Be explicit. If you know the run ID: ```text theme={null} Implement run ``` If you want to check which runs are active before resuming: ```bash theme={null} python scripts/recursive-status.py --repo-root . ``` If you want to resume from a specific plan artifact: ```text theme={null} Implement the plan at /.recursive/run//02-to-be-plan.md ``` The agent will ask for clarification if the command is ambiguous and no single active run can be identified. # Installation Source: https://recursive-mode.dev/installation All installation options for Recursive Mode: skills CLI, Python, PowerShell, and Bash. recursive-mode is installed in two steps: add the skill package to your agent environment, then bootstrap the target repository with the scaffold. Bootstrapping happens automatically the first time you invoke recursive-mode. ## Prerequisites Before installing, confirm you have: * A git repository to bootstrap * The skills CLI available (`npx skills`) * Python 3, PowerShell (`pwsh`), or Bash — depending on which bootstrap script you use * An agent environment that supports the skills CLI ## Install options The skills CLI is the preferred way to install and manage recursive-mode in your agent environment. **Install the main skill** ```bash theme={null} npx skills add try-works/recursive-mode ``` **List everything in the package** ```bash theme={null} npx skills add try-works/recursive-mode --list ``` Add `--full-depth` to list nested subskills as well: ```bash theme={null} npx skills add try-works/recursive-mode --list --full-depth ``` **Install all included skills** ```bash theme={null} npx skills add try-works/recursive-mode --skill '*' --full-depth ``` **Install a single subskill** To install only one subskill instead of the full package, pass its name with `--skill`: ```bash theme={null} npx skills add try-works/recursive-mode --skill recursive-tdd --full-depth ``` Replace `recursive-tdd` with any of the available subskills: `recursive-worktree`, `recursive-debugging`, `recursive-review-bundle`, or `recursive-subagent`. After the skill package is installed, run one of the bootstrap scripts to create the `/.recursive/` scaffold in your target repository. Run the script that matches your environment from your repository root: ```bash Bash theme={null} bash "/scripts/install-recursive-mode.sh" --repo-root . ``` ```python Python theme={null} python "/scripts/install-recursive-mode.py" --repo-root . ``` ```powershell PowerShell theme={null} pwsh -NoProfile -File "/scripts/install-recursive-mode.ps1" -RepoRoot . ``` Replace `` with the path where the skill package was installed, and `.` with your repository root path if you are not already in it. **Available flags** | Script | Flag | Description | | ---------- | ------------------------- | -------------------------------------------------------- | | Python | `--repo-root ` | Repository root path. Defaults to the current directory. | | Python | `--skip-recursive-update` | Skip the canonical `RECURSIVE.md` upsert. | | PowerShell | `-RepoRoot ` | Repository root path. Defaults to the current directory. | | PowerShell | `-SkipRecursiveUpdate` | Skip the canonical `RECURSIVE.md` upsert. | The Bash script (`install-recursive-mode.sh`) is a thin wrapper that delegates to the Python script, so it accepts the same flags as the Python version. The bootstrap scripts are safe to re-run. They upsert managed blocks and preserve any unrelated existing file content. Use them to update an existing scaffold when you upgrade the skill package. ## What gets installed Running the bootstrap script creates the following layout in your repository: ```text theme={null} /.recursive/ ├── RECURSIVE.md # Canonical workflow spec ├── STATE.md # Current repository state ├── DECISIONS.md # Decisions ledger ├── run/ # Run artifact directory │ └── .gitkeep └── memory/ ├── MEMORY.md # Durable memory router ├── domains/ # Stable functional-area knowledge ├── patterns/ # Reusable playbooks and solution patterns ├── incidents/ # Recurring failure signatures and fixes ├── episodes/ # Distilled lessons from specific runs ├── archive/ # Historical or deprecated memory docs └── skills/ ├── SKILLS.md # Skill memory router ├── availability/ # Environment-specific skill availability notes ├── usage/ # Stable usage guidance per skill ├── issues/ # Recurring skill failures and limitations └── patterns/ # Reusable multi-skill operating patterns ``` ### Key files | File | Purpose | | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- | | `/.recursive/RECURSIVE.md` | The canonical workflow contract. Your agent reads this to understand phase order, audit rules, lock rules, and memory maintenance. | | `/.recursive/STATE.md` | Tracks current repository state. Updated during closeout phases. | | `/.recursive/DECISIONS.md` | Ledger of decisions made across runs. | | `/.recursive/memory/MEMORY.md` | Memory router. Agents read this before loading any memory docs. | | `/.recursive/run/` | Each run gets a subdirectory here: `/.recursive/run//`. | ### The memory router The memory layer under `/.recursive/memory/` stores durable project knowledge — domain context, reusable patterns, recurring incidents, and skill guidance — separately from current repository state and individual run artifacts. This separation lets the workflow distinguish between what is true right now, what happened in one run, and what has been learned across many runs. Agents load only the memory docs relevant to the current task rather than reading the full memory tree on every run. ### Subskills included The package ships these installable subskills alongside the root `recursive-mode` skill: | Subskill | Purpose | | ------------------------- | ------------------------------------------------------------- | | `recursive-worktree` | Isolates implementation work in a dedicated git worktree | | `recursive-tdd` | Strict or pragmatic TDD with recorded RED/GREEN evidence | | `recursive-debugging` | Structured debugging with durable artifact capture | | `recursive-review-bundle` | Packages delegated reviews into canonical review bundles | | `recursive-subagent` | Records and verifies subagent contributions before acceptance | Install the full set with `--skill '*' --full-depth`, or install individual subskills by name. # Introduction to recursive-mode Source: https://recursive-mode.dev/introduction What recursive-mode is, who it's for, and the problems it solves. recursive-mode is an installable skill package for structured AI-assisted software development. It gives your agent a file-backed workflow for requirements, planning, implementation, testing, review, closeout, and memory — instead of leaving that entire process scattered across chat history. ## Solving the problem of context rot Long-running agent work has a common failure mode: requirements, decisions, and plans live in the conversation. Once that session ends or the context window overflows, the agent loses track of what was decided, what was implemented, and why. This is **context rot**. recursive-mode solves it by making static repository documents the source of truth for every phase. Requirements, plans, and evidence live in files that persist across sessions, contributors, and repositories. Prompts become short commands, not specifications. ## Recursion in practice recursive-mode builds on a couple of simple principles: Each development phase produces one locked output document. Each phase uses the previous phases' output as its input. Before exiting a phase and preceeding to next, a certain set of criteria, based on the workflow as well as previous phase docs, must be fulfilled and if not, the agent needs to iterate until it reaches exit criteria. recursive-mode is "recursive" because the process continuously revisits its own outputs. Each phase consumes artifacts from earlier phases. Audited phases loop through `draft → audit → repair → re-audit` until the work is genuinely ready. Closeout phases feed validated lessons back into decisions, state, and memory so future runs start from better context. Later work always refers back to earlier work. ## Docs for development and traceability With recursive-mode, all information that is important to the development workflow is stored in durable docs. This is the folder structure of a recursive run: ```text theme={null} .recursive/ ├── /memory/ # Structured memory bank ├── RECURSIVE.md # Canonical workflow spec ├── STATE.md # Current repository state ├── DECISIONS.md # Decisions ledger ├── run/00-my-first-requirements/ ├── 00-requirements.md # User-created requirement ├── 01-as-is.md # Analysis of codebase current state ├── 02-to-be.md # Implementation plan ├── 03-implementation-summary.md # What was done in practice ├── 04-test-summary.md # Automated test summary ├── 05-manual-qa.md # Test cases └── addenda/ # Addenda docs added as needed ``` Global STATE.md and DECISIONS.md are read at the start of and updated at the end of each run. ## Docs for humans and machines, and for fine-tuning and self-distillation Docs are human-readable and machine-readable. They offer the best traceability out of any skill or harness in 2026. Your entire rationale for building the way you did (or what the agent decided to do) is clearly recorded and referenceable. The run docs together with the code diff in the worktrees become a rich dataset for auto-training or finetuning a model against your codebase. ## Chat is CLI Chat is used the way to should be, for commands only. You can start by using plan mode and refine the plan with the agent and then ask it to turn the plan into a new recursive run. You can also create the run folder and requirements doc yourself, then ask the agent to "implement run 01". The main point is: keep valuable information out of chat and in docs. ## An alternative to Missions recursive-mode, previously known as rlm-workflow, is a free alternative that pre-dates Factory.ai's Missions feature by several months. It has a stronger recursion mechanism, is free and open source, and works in any IDE, CLI, agent and with any models. ## Who it's for * **Developers who want auditable agent runs** — every phase is recorded in repo files, not in ephemeral chat * **Teams who need recorded evidence** — requirements and implementation outcomes are captured as durable artifacts * **Users running long or resumable work** — runs can be paused and resumed without losing context ## Key benefits Keep important implementation context in repository files instead of losing it in chat history. Make agent work easier to audit, review, and resume — even across sessions and contributors. Reduce vague "done" claims by requiring explicit evidence and phase completion records. Improve reliability through structured planning, testing, review, and closeout phases. Make delegated or subagent work safer by requiring the controller to verify results against real files and diffs. Preserve project decisions and operational lessons in a reusable memory layer that future runs can build on. ## What's included recursive-mode ships these installable skills: | Skill | Purpose | | ------------------------- | ---------------------------------------------------------------------------- | | `recursive-mode` | Core workflow orchestration: staged phases, locked artifacts, durable memory | | `recursive-worktree` | Isolates implementation work in a dedicated git worktree | | `recursive-debugging` | Structured debugging with explicit root-cause analysis (Phase 1.5) | | `recursive-tdd` | Strict or pragmatic TDD with recorded RED/GREEN evidence | | `recursive-review-bundle` | Packages delegated code reviews into canonical, reproducible bundles | | `recursive-subagent` | Controls subagent handoff contracts and self-audit fallback | Install the full package: ```bash theme={null} npx skills add try-works/recursive-mode --skill '*' --full-depth ``` Or install a single subskill: ```bash theme={null} npx skills add try-works/recursive-mode --skill recursive-tdd --full-depth ``` # Quick Start Source: https://recursive-mode.dev/quickstart Get a repository running with recursive-mode in under 5 minutes. This guide walks you through installing the skill package, bootstrapping your repository, and starting your first run. Add recursive-mode to your agent environment with the skills CLI: ```bash theme={null} npx skills add try-works/recursive-mode ``` This installs the root `recursive-mode` skill. To see everything included in the package before installing, run: ```bash theme={null} npx skills add try-works/recursive-mode --list ``` Run the installer against your target repository. Choose the script that matches your environment: ```bash Bash theme={null} bash "/scripts/install-recursive-mode.sh" --repo-root . ``` ```python Python theme={null} python "/scripts/install-recursive-mode.py" --repo-root . ``` ```powershell PowerShell theme={null} pwsh -NoProfile -File "/scripts/install-recursive-mode.ps1" -RepoRoot . ``` Replace `` with the path where the skill was installed. Run this command from your repository root, or pass the path explicitly with `--repo-root `. The bootstrap script creates the entire `/.recursive/` scaffold in your repository, including: * `/.recursive/RECURSIVE.md` — the canonical workflow spec * `/.recursive/STATE.md` — current repository state * `/.recursive/DECISIONS.md` — decisions ledger * `/.recursive/memory/MEMORY.md` — durable memory router * `/.recursive/memory/skills/SKILLS.md` — skill memory router * `/.recursive/memory/{domains,patterns,incidents,episodes,archive}/` — memory shards * `/.recursive/memory/skills/{availability,usage,issues,patterns}/` — skill memory shards * `/.recursive/run/` — directory for run artifacts The script is safe to re-run. It upserts managed blocks and preserves any unrelated existing content. Confirm the scaffold was created correctly by listing the `/.recursive/` directory: ```bash theme={null} ls .recursive/ ``` You should see: `AGENTS.md`, `DECISIONS.md`, `RECURSIVE.md`, `STATE.md`, `memory/`, and `run/`. The canonical workflow contract that your agent will follow lives in: ```text theme={null} /.recursive/RECURSIVE.md ``` If your agent needs a lightweight index of what to read under `/.recursive/`, it should start with `/.recursive/AGENTS.md`. Once the repository is bootstrapped and your requirements or plan live in repository files, start a run with a short command: ```text theme={null} Implement the run ``` Other valid entry commands: ```text theme={null} Implement run 75 Implement the plan Create a new run based on the plan Start a recursive run ``` Requirements stay in repository documents — not in prompts. Keep your commands short and command-like. The agent reads the relevant repo files to understand what to do. The agent creates a run directory under `/.recursive/run//` and begins progressing through the audited phases defined in `/.recursive/RECURSIVE.md`. # Install Script Source: https://recursive-mode.dev/scripts/install Reference for install-recursive-mode — the bootstrapper that creates the /.recursive/ control-plane scaffold in your repository. `install-recursive-mode` creates the canonical `/.recursive/` control-plane layout inside a target repository. Run it once after installing the Recursive Mode skill package to prepare any repo for recursive-mode runs. ## What it does The installer performs the following actions: * Creates the `/.recursive/` control-plane directory tree * Upserts the canonical workflow spec into `/.recursive/RECURSIVE.md` * Creates the memory plane under `/.recursive/memory/` with all required subdirectories * Initializes `/.recursive/STATE.md` and `/.recursive/DECISIONS.md` * Preserves any unrelated content in files it touches ## Usage ```bash Python theme={null} python scripts/install-recursive-mode.py --repo-root . ``` ```powershell PowerShell theme={null} pwsh -NoProfile -File scripts/install-recursive-mode.ps1 -RepoRoot . ``` ```bash Bash theme={null} bash scripts/install-recursive-mode.sh --repo-root . ``` Replace `.` with the path to your repository root if you are running the script from a different directory. ## What gets created After running the installer, your repository will contain the following scaffold: ``` .recursive/ ├── RECURSIVE.md # Canonical workflow spec ├── STATE.md # Current repository state ledger ├── DECISIONS.md # Decision ledger and run index ├── run/ │ └── .gitkeep └── memory/ ├── MEMORY.md # Durable memory router ├── domains/ ├── patterns/ ├── incidents/ ├── episodes/ ├── archive/ └── skills/ ├── SKILLS.md # Skill memory router ├── availability/ ├── usage/ ├── issues/ └── patterns/ ``` Each memory subdirectory contains a `.gitkeep` file so the directory is tracked by Git even before any memory docs are added. ## Idempotency The installer is safe to run multiple times. It uses marker-delimited upserts for managed blocks, so re-running it refreshes the canonical workflow spec and bridge docs without overwriting any content you have added outside those blocks. Files that already exist are not truncated or replaced. Run the installer again after upgrading the Recursive Mode skill package to pull in the latest canonical workflow spec and bridge content. ## Options | Flag | Default | Description | | -------------------------------------------------- | ------- | ------------------------------------------------- | | `--repo-root` / `-RepoRoot` | `.` | Path to the repository root to bootstrap | | `--skip-recursive-update` / `-SkipRecursiveUpdate` | `false` | Skip the `RECURSIVE.md` canonical workflow upsert | # Lock & Verify Source: https://recursive-mode.dev/scripts/lock-and-verify Reference for recursive-lock and verify-locks — tools for locking phase artifacts and verifying lock integrity. Use `recursive-lock` to lock a phase artifact once it has passed audit. Use `verify-locks` to confirm that all locked artifacts in a run still match their stored hashes. *** ## recursive-lock `recursive-lock` finalizes a phase artifact by writing three fields into it: * `Status: LOCKED` — marks the artifact as immutable * `LockedAt` — records the UTC timestamp of the lock * `LockHash` — a SHA-256 hash of the artifact content (excluding the `LockHash` line itself) The script validates the artifact's gates and audit discipline before writing the lock fields, so it will refuse to lock an artifact that has unresolved lint failures. ### Why use the script The `LockHash` must be computed from normalized content (CRLF-normalized, `LockHash` line stripped) using a specific algorithm. If you write the lock fields by hand, the hash will almost certainly be wrong, and `verify-locks` will report the artifact as tampered. Do not manually edit `Status`, `LockedAt`, or `LockHash` in a phase artifact. Always use `recursive-lock` to write these fields. Manual edits will invalidate the hash and cause `verify-locks` to fail. ### Usage ```bash Python theme={null} python scripts/recursive-lock.py --repo-root . --run-id --phase 03-implementation-summary.md ``` ```powershell PowerShell theme={null} pwsh -NoProfile -File scripts/recursive-lock.ps1 -RepoRoot . -RunId -Phase 03-implementation-summary.md ``` Replace `` with your run directory name and `--phase` / `-Phase` with the filename of the artifact you want to lock (for example, `01-as-is.md`, `02-to-be-plan.md`). ### Pre-lock validation Before writing lock fields, the script runs the same checks as `lint-recursive-run`. If any lint failures are found, the lock is aborted and the failures are printed. Fix the artifact, then run `recursive-lock` again. Run `lint-recursive-run` first to see all issues at once, then fix them before calling `recursive-lock`. The lock script stops at the first blocking failure, so lint gives you a more complete picture. *** ## verify-locks `verify-locks` iterates over all artifacts in a run that carry a `LockHash` field and recomputes the hash from the current file content. Any artifact whose recomputed hash does not match the stored hash is reported as potentially tampered or corrupted. ### What it checks * Every artifact with `Status: LOCKED` has a `LockHash` field * The recomputed SHA-256 hash of each locked artifact matches its stored `LockHash` * `LockedAt` is present and parseable ### Usage ```bash Python theme={null} python scripts/verify-locks.py --repo-root . --run-id ``` ```powershell PowerShell theme={null} pwsh -NoProfile -File scripts/verify-locks.ps1 -RepoRoot . -RunId ``` ### When to run Run `verify-locks` in the following situations: * **Before merging** — confirm that no locked artifact was edited after locking * **After any artifact edit** — if you needed to correct a locked artifact using an addendum, verify that the lock fields are still intact on the original artifact * **As a CI hygiene check** — add `verify-locks` to your CI pipeline to catch accidental edits to locked history Recursive Mode does not rewrite locked history. If you need to correct a locked phase, add an addendum artifact and reconcile it in the downstream phase — do not edit the locked file directly. Hash mismatches can result from line-ending normalization by your editor, Git, or OS tools. The lock hash is computed from LF-normalized content, so any tool that converts line endings can silently invalidate a hash. Check your Git `core.autocrlf` and editor settings. Do not edit the locked file. Instead, create an addendum artifact in the run directory and explicitly reconcile the correction in the next downstream phase. Record the addendum in the `Inputs` section of any phase that depends on the corrected information. # Scripts Source: https://recursive-mode.dev/scripts/overview Reference overview of all scripts included with recursive-mode — cross-platform utilities for bootstrapping, status checks, linting, locking, and more. recursive-mode ships a set of cross-platform utility scripts for managing the control-plane lifecycle of your repository. Every script is available in two forms: * **Python** (`.py`) — works on any platform with Python 3 installed * **PowerShell** (`.ps1`) — works on Windows, macOS, and Linux with PowerShell 7+ The install script also ships a **Bash** (`.sh`) variant for environments where Python is not available at bootstrap time. When both Python and PowerShell are available, prefer the Python variant. The Python scripts are the reference implementation; PowerShell scripts mirror their behavior. ## Script reference | Script | Purpose | | ------------------------------------------- | ----------------------------------------------------------------------------------------------------- | | `install-recursive-mode` (.py / .ps1 / .sh) | Bootstrap a repository with the `/.recursive/` control-plane scaffold, bridge docs, and memory layout | | `recursive-init` (.py / .ps1) | Initialize a new run directory under `/.recursive/run//` | | `recursive-status` (.py / .ps1) | Show run status, lock-chain validity, and audit blockers for a run | | `lint-recursive-run` (.py / .ps1) | Lint artifact structure, required header fields, gate completeness, and lock fields | | `recursive-lock` (.py / .ps1) | Lock a phase artifact by writing `Status: LOCKED`, `LockedAt`, and a SHA-256 `LockHash` | | `verify-locks` (.py / .ps1) | Verify that all locked artifacts in a run still match their stored `LockHash` | | `recursive-review-bundle` (.py / .ps1) | Generate a canonical review bundle for delegated audit or review | | `recursive-subagent-action` (.py / .ps1) | Generate a subagent action record scaffold under `/.recursive/run//subagents/` | | `recursive-closeout` (.py / .ps1) | Scaffold closeout artifacts for phases 4–8 | | `check-reusable-repo-hygiene` (.py / .ps1) | Check a reusable skill or workflow repository for committed run residue | ## How to run Get help for any script by passing `--help` (Python) or `-Help` (PowerShell): ```bash Python theme={null} python scripts/recursive-status.py --help ``` ```powershell PowerShell theme={null} pwsh -NoProfile -File scripts/recursive-status.ps1 -Help ``` Replace `recursive-status` with the name of whichever script you want to inspect. # Status & Lint Source: https://recursive-mode.dev/scripts/status-and-lint Reference for recursive-status and lint-recursive-run — tools for checking run status, lock-chain validity, and artifact structure. Use `recursive-status` to get a high-level view of a run's progress and health. Use `lint-recursive-run` to validate artifact structure in detail before locking a phase. *** ## recursive-status `recursive-status` shows the current state of a run: which phases are complete, which are locked, which have audit blockers, and whether the lock chain is intact. ### What it shows * Phase-by-phase status (draft, pass, locked) * Lock-chain validity for each locked artifact * Audit blockers that would prevent a phase from passing * Missing required fields or malformed lock fields ### Usage ```bash Python theme={null} python scripts/recursive-status.py --repo-root . --run-id ``` ```powershell PowerShell theme={null} pwsh -NoProfile -File scripts/recursive-status.ps1 -RepoRoot . -RunId ``` Replace `` with the run directory name under `/.recursive/run/` (for example, `2026-04-09-add-search`). ### Output The script prints a summary for each phase artifact found in the run directory. For each artifact you will see: * The phase filename and its current `Status` field value * Whether the phase is `LOCKED` and whether the `LockHash` is still valid * Any audit blockers (for example, a missing `Audit: PASS` line, an undeclared TDD mode, or a requirement with no disposition) Run `recursive-status` before starting a new phase to confirm all upstream artifacts are locked and their hashes are intact. *** ## lint-recursive-run `lint-recursive-run` performs a thorough structural audit of all phase artifacts in a run. It checks artifact headers, required sections, gate completeness, lock fields, and audit-discipline rules. ### What it checks * Required header fields are present and non-empty * Audited phases include all required audit sections (`Audit Context`, `Effective Inputs Re-read`, and others) * Gate fields (`Coverage`, `Approval`, `Audit`) are present and hold valid values * `Status: LOCKED` artifacts have both `LockedAt` and `LockHash` fields * Requirement traceability entries exist for every in-scope `R#` in the applicable artifacts * TDD mode is declared in `03-implementation-summary.md` * QA execution mode is declared in `05-manual-qa.md` * Diff basis fields are present in all diff-audited artifacts ### Usage ```bash Python theme={null} python scripts/lint-recursive-run.py --repo-root . --run-id ``` ```powershell PowerShell theme={null} pwsh -NoProfile -File scripts/lint-recursive-run.ps1 -RepoRoot . -RunId ``` ### When to run lint Run `lint-recursive-run` before locking any phase artifact. Locking a phase that has lint failures will result in a `LockHash` that is computed from an incomplete or non-conforming artifact, which is harder to correct after the fact. `recursive-status` and `lint-recursive-run` check overlapping but distinct things. The status script focuses on lock-chain integrity and high-level phase progression; the lint script checks structural conformance in detail. Run both before locking a phase. Late-phase artifacts (phases 6, 7, and 8) are compact delta receipts that point to control-plane docs. Some audit-section requirements apply to these phases; check the lint output message for the specific field or heading that is missing. # Debugging Source: https://recursive-mode.dev/subskills/recursive-debugging Insert Phase 1.5 to find root cause before planning any fix. ## Overview The `recursive-debugging` subskill inserts a mandatory Phase 1.5 between Phase 1 (AS-IS) and Phase 2 (TO-BE Plan) whenever a requirement involves fixing a bug, investigating a test failure, or understanding unexpected behavior. It enforces systematic root cause analysis before any fix is attempted. ```bash theme={null} npx skills add try-works/recursive-mode --skill recursive-debugging --full-depth ``` **Core principle:** Always find the root cause before attempting fixes. Symptom fixes are failure. ## The Iron Law **NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST.** Skipping Phase 1.5 to attempt a quick fix is not faster — it creates rework, new bugs, and thrashing. Systematic debugging is faster than guess-and-check, even under time pressure. ## When to Use Insert Phase 1.5 whenever: * A requirement is a bug fix * Tests are failing and you need to understand why * Behavior is unexpected or intermittent * A performance problem needs investigation * Integration issues are reported Use it **especially** when you feel pressure to skip it: emergencies, "obvious" fixes, and repeated failed fix attempts are all signs that the process matters more, not less. ## How Phase 1.5 Fits Phase 1.5 sits between AS-IS analysis and planning: ``` Phase 1: 01-as-is.md (captures current behavior) ↓ Phase 1.5: 01.5-root-cause.md (this subskill) ↓ Phase 2: 02-to-be-plan.md (fix plan based on confirmed root cause) ``` Lock Phase 1 first. Then create `01.5-root-cause.md` with `Status: DRAFT` and work through the four steps below. Lock Phase 1.5 when root cause is confirmed. Phase 2 then consumes the findings from Phase 1.5. ## The Four Steps Read error messages and stack traces completely before doing anything else. They often contain the exact location of the problem. Record in the artifact: ```markdown theme={null} ## Error Analysis **Error Message:** [verbatim] **Stack Trace:** [key frames] **File:Line:** [locations] **Error Code:** [if applicable] **Key Insight:** [what the error is telling you] ``` Then verify you can reproduce the issue reliably. If you cannot reproduce it, gather more data — do not guess. ```markdown theme={null} ## Reproduction Verification **Steps:** 1. [exact step] 2. [exact step] **Reproducible:** Yes / No / Intermittent **Frequency:** [X out of Y attempts] **Deterministic:** Yes / No ``` Find the difference between working and broken code before proposing any fix. * Locate similar working code in the same codebase * Compare the working and broken paths line by line * Check recent commits, dependency changes, and config changes for what could have introduced the problem * Trace data flow backward through the call stack to find where the bad value originates Record in the artifact: ```markdown theme={null} ## Pattern Analysis **Working Example:** [file:location] **Broken Code:** [file:location] **Key Differences:** | Aspect | Working | Broken | |--------|---------|--------| | [X] | [value] | [value] | **Likely Cause:** [difference that explains the bug] **Dependencies:** [what the code needs to work] ``` Form one clear hypothesis. Make the smallest possible change to test it. One variable at a time. ```markdown theme={null} ## Hypothesis Testing ### Hypothesis 1 **Statement:** I think X is the root cause because Y **Rationale:** [why you think this] **Test:** [minimal change to verify] **Result:** confirmed / rejected **Evidence:** [output or observation] ``` If the hypothesis is rejected, form a new one. Do not stack multiple fixes on top of each other to see if something works. If you genuinely don't understand something, say so. Do not pretend to know the root cause. Research more or ask for help. Once root cause is confirmed, write a summary that Phase 2 can build directly from. ```markdown theme={null} ## Root Cause Summary **Root Cause:** [one sentence] **Location:** [file:line] **Explanation:** [paragraph explaining why] **Fix Approach:** [high-level] **Test Strategy:** [how to verify the fix] ``` This summary becomes the input to Phase 2's fix plan and test strategy. Do not begin fixing until Phase 1.5 is locked. ## Output Artifact Write the artifact to: ``` /.recursive/run//01.5-root-cause.md ``` The artifact must close with a Coverage Gate and Approval Gate before it can be locked: ```markdown theme={null} ## Coverage Gate - [ ] Error messages analyzed - [ ] Reproduction verified - [ ] Recent changes reviewed - [ ] Data flow traced to source - [ ] Pattern analysis completed - [ ] Hypothesis tested and confirmed - [ ] Root cause documented - [ ] Fix strategy defined Coverage: PASS / FAIL ## Approval Gate - [ ] Root cause identified (not just symptom) - [ ] Fix approach clear - [ ] Test strategy defined - [ ] No "quick fixes" attempted - [ ] Ready to proceed to Phase 2 Approval: PASS / FAIL ``` ## Red Flags Stop and return to the systematic process if you catch yourself thinking any of the following: * "Quick fix for now, investigate later" * "Just try changing X and see if it works" * "Add multiple changes, run tests" * "It's probably X, let me fix that" * "I don't fully understand but this might work" * You are proposing solutions before tracing data flow * You are on your third failed fix attempt If you have made three or more failed fix attempts, stop fixing. The pattern indicates an architectural problem. Document the attempts in Phase 1.5, question whether the approach is sound, and decide whether a deeper refactor is needed before continuing. ## Common Shortcuts to Reject | Excuse | Why It's Wrong | | ------------------------------------------ | ------------------------------------------------------------------------------- | | "Issue is simple, don't need process" | Simple issues have root causes too. The process is fast for simple bugs. | | "Emergency, no time for process" | Systematic debugging is faster than guess-and-check thrashing. | | "I see the problem, let me fix it" | Seeing symptoms is not the same as understanding root cause. | | "Multiple fixes at once saves time" | You can't isolate what worked. Multiple simultaneous changes cause new bugs. | | "One more fix attempt" (after 2+ failures) | Three or more failures indicate an architectural problem. Question the pattern. | # Review Bundle Source: https://recursive-mode.dev/subskills/recursive-review-bundle Package a canonical context bundle before delegating a Phase 3.5 review or audit. ## Overview The `recursive-review-bundle` subskill generates a durable, reproducible context bundle before you delegate an audit or review to a subagent. Without a canonical bundle, delegated reviews are context-free and cannot be accepted by the recursive-mode workflow. ```bash theme={null} npx skills add try-works/recursive-mode --skill recursive-review-bundle --full-depth ``` ## When to Use Use this subskill whenever you are delegating a Phase 3.5 code review, test review, or other audit to a subagent. Generate the bundle before dispatching the reviewer, and refresh it after any material repairs or scope changes. This subskill packages the handoff context. It does not replace the canonical workflow in `/.recursive/RECURSIVE.md` and it does not perform the review itself. ## The Canonical Scripts Two scripts ship with recursive-mode for generating review bundles: * `scripts/recursive-review-bundle.py` — use when Python is available * `scripts/recursive-review-bundle.ps1` — use when the delegated path is PowerShell-oriented Prefer the Python script when both toolchains are available. ## Minimum Required Inputs Every bundle invocation must include all of the following: | Input | Description | | ----------------------- | ------------------------------------------------------ | | `repo root` | Path to the repository root | | `run id` | The current recursive-mode run ID | | `phase name` | The phase being reviewed (e.g., `03.5 Code Review`) | | `reviewer role` | The canonical role (e.g., `code-reviewer`) | | `artifact path` | Path to the artifact being reviewed | | `upstream artifacts` | Exact paths to all artifacts the reviewer must re-read | | `audit questions` | The specific questions the review must answer | | `required output shape` | The format the reviewer's output must take | Add evidence refs or addenda paths explicitly when they are relevant — the bundle generator will also auto-discover applicable addenda and skill-memory refs. ## Commands ```bash Python theme={null} python scripts/recursive-review-bundle.py \ --repo-root . \ --run-id "" \ --phase "03.5 Code Review" \ --role code-reviewer \ --artifact-path "/.recursive/run//03.5-code-review.md" \ --upstream-artifact "/.recursive/run//00-requirements.md" \ --upstream-artifact "/.recursive/run//02-to-be-plan.md" \ --audit-question "Which R# remain incomplete?" \ --required-output "Findings ordered by severity" ``` ```powershell PowerShell theme={null} pwsh -NoProfile -File scripts/recursive-review-bundle.ps1 ` -RepoRoot . ` -RunId "" ` -Phase "03.5 Code Review" ` -Role code-reviewer ` -ArtifactPath "/.recursive/run//03.5-code-review.md" ` -UpstreamArtifact "/.recursive/run//00-requirements.md","/.recursive/run//02-to-be-plan.md" ` -AuditQuestion "Which R# remain incomplete?" ` -RequiredOutput "Findings ordered by severity" ``` ## Acceptance Rules After generating the bundle, follow these rules before and after delegation: Record `Review Bundle Path` in the delegated phase artifact. Without a recorded path, the phase cannot be considered properly delegated. The reviewer must reference the bundle path, name the upstream artifacts they re-read, cite relevant addenda, reference the changed files or code they reviewed, and provide a final verdict. A bare bundle file is not proof of review quality — the written review must use the bundle contents. If material repairs or scope changes occur after the bundle was generated, regenerate it before sending to the reviewer. A stale bundle invalidates the review. Do not treat a delegated review as accepted if the reviewer's output does not cite the bundle, upstream artifacts, and changed files. Generic summaries with no grounded findings must be rejected. See the [Subagent](/subskills/recursive-subagent) page for the full output rejection checklist. ## Bundle Location Canonical bundles are stored under: ``` /.recursive/run//evidence/review-bundles/ ``` Reference this path in the phase artifact and in the handoff to the subagent so the review is durable and repeatable across sessions. # Subagent Source: https://recursive-mode.dev/subskills/recursive-subagent Decide whether and how to delegate phases to subagents, and enforce the handoff contract when you do. ## Overview The `recursive-subagent` subskill defines when to delegate a recursive-mode phase to a subagent, how to structure the handoff, and when to reject a delegated result. It also defines the self-audit fallback for environments where subagents are not available. ```bash theme={null} npx skills add try-works/recursive-mode --skill recursive-subagent --full-depth ``` ## When to Use Consider delegating to a subagent when a phase would benefit from an independent audit, a code review, or a bounded implementation with a clearly separate write scope. Subagents are optional accelerators — they are never required infrastructure. The main agent remains responsible at all times for: * one active recursive phase per run * full audit rigor before lock * verifying delegated work against real files, diffs, and artifacts * falling back to self-audit when subagents are unavailable ## Priority of Use When subagents are available, use them in this order of value: | Priority | Role | | -------- | ---------------------------------------------------------- | | 1 | Phase auditor | | 2 | Traceability auditor | | 3 | Code reviewer | | 4 | Memory auditor | | 5 | Test reviewer | | 6 | Bounded implementer (only for truly disjoint write scopes) | Audit, review, and read-only verification are the safest default delegation modes. ## Capability Detection Capability detection is a hard control point. At the start of any phase where you are considering delegation, determine whether your environment actually supports subagents. **If subagents are unavailable:** ```markdown theme={null} Subagent Availability: unavailable Audit Execution Mode: self-audit ``` Perform the same audit locally. Do not weaken or skip it. **If subagents are available:** ```markdown theme={null} Subagent Availability: available ``` Decide whether delegation materially helps for this specific phase. Keep the same audit checklist and acceptance standard either way. Before delegating, read `/.recursive/memory/skills/SKILLS.md` and the relevant skill-memory shards for delegated review fit, review-bundle fit, and stale-context risks. ## The Delegated Audit Contract A delegated audit is only valid when you pass a complete context bundle. The controller must pass all 11 items: 1. Phase name and artifact path 2. Current phase draft 3. Exact upstream artifact paths that must be re-read 4. Relevant addendum paths 5. Relevant prior recursive evidence and memory refs 6. Diff basis from `00-worktree.md` 7. Changed file list 8. Targeted code file paths or file groups to inspect 9. Relevant control-plane docs when needed 10. Exact audit questions or checklist for the phase 11. Required output shape including findings and verdict Vague delegation such as "review this phase" or "audit implementation" is invalid. If any required item is missing, do not delegate — perform the audit yourself. Prefer generating the bundle with `recursive-review-bundle` and passing the bundle path as part of the handoff. ## Output Rejection Rules Reject a delegated result if any of the following are true: * It does not cite the artifact path or phase name * It does not cite the review bundle path or clearly restate the same bundle contents * It does not mention the upstream artifacts re-read * It ignores relevant addenda that were part of the effective input set * It ignores relevant prior recursive evidence or memory refs in the bundle * It does not review the diff basis or changed files * It does not cite changed files or code refs in the review narrative * The controller did not verify claimed success against actual files, actual artifacts, and actual diff-owned scope * It cannot be translated into a durable subagent action record without guessing * It does not address requirement or plan alignment where required * It gives only generic praise with no grounded findings * It has no explicit verdict Do not accept stale delegated context silently. If repairs were made after the subagent's review, record the concrete repair performed after verification. ## Canonical Roles ### Phase Auditor Use for any audited phase that needs an independent pass over the current draft, upstream locked artifacts, the git diff versus the recorded baseline, and requirement coverage. The auditor identifies gaps, drift, and repair needs. ### Traceability Auditor Use when you need to verify that downstream artifacts explicitly cover every in-scope `R#` and do not hide behind vague summaries. Traceability auditors check that `implemented` and `verified` dispositions cite concrete changed files and distinct verification evidence. ### Code Reviewer Use for Phase 3.5 or high-risk Phase 3 and Phase 4 audits. The code reviewer checks: * Requirements versus implementation * Plan versus implementation * Git diff versus claimed scope * Code quality and maintainability * Test adequacy and TDD compliance ### Memory Auditor Use in Phase 8 to verify that touched paths, memory status transitions, and router updates match the final validated repo state. ### Test Reviewer Use in Phase 4 to audit test adequacy, exact test commands, evidence capture, and whether the implementation is truly complete before trusting test results. ## Self-Audit Fallback When subagents are unavailable, reuse the same checklist in the phase artifact and record: ```markdown theme={null} ## Audit Context Audit Execution Mode: self-audit Subagent Availability: unavailable Audit Inputs Provided: - `/.recursive/run//...` ``` Then complete the full audit loop locally: Never set `Coverage: PASS` or `Approval: PASS` for an audited phase unless the artifact ends with `Audit: PASS`. # TDD Source: https://recursive-mode.dev/subskills/recursive-tdd Enforce strict RED-GREEN-REFACTOR discipline in every recursive-mode implementation phase. ## Overview The `recursive-tdd` subskill makes test-driven development mandatory for all Phase 3 implementation work — new features, bug fixes, refactors, and behavior changes. It enforces the cycle rigorously and requires you to record evidence in the Phase 3 artifact so recursive-mode tooling can verify compliance. ```bash theme={null} npx skills add try-works/recursive-mode --skill recursive-tdd --full-depth ``` **Core principle:** If you didn't watch the test fail, you don't know if it tests the right thing. ## The Iron Law **NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST.** This rule has no silent exceptions. If strict RED-first flow is genuinely infeasible, you must declare `TDD Mode: pragmatic` in the Phase 3 artifact, record a concrete reason, and provide compensating validation evidence. Silence is not an option. ## When to Use Apply this subskill in Phase 3 for every type of implementation work: * New features * Bug fixes * Refactoring * Behavior changes There is no "this is too simple" exemption. There is no "under pressure" bypass. There is only strict mode or explicitly declared pragmatic mode. ## The RED-GREEN-REFACTOR Cycle Write the smallest possible test that describes what the code should do. One behavior per test, clear name, real assertion against real code. **Good test:** ```typescript theme={null} test('rejects empty email with clear error message', async () => { const result = await submitForm({ email: '' }); expect(result.error).toBe('Email is required'); }); ``` **Bad test** (tests mock behavior, not real behavior): ```typescript theme={null} test('email validation works', async () => { const mock = jest.fn().mockResolvedValue({ valid: true }); const result = await validateEmail(mock); expect(mock).toHaveBeenCalled(); }); ``` Run the test and confirm it **fails** — not errors, fails — and for the right reason: ```bash theme={null} npm test path/to/test.test.ts ``` Record the failure output in the Phase 3 artifact under `RED Evidence`. Confirm three things before moving on: * The test **fails** (not errors out) * The failure message matches what you expected * The failure is because the feature is missing, not because of a typo If the test passes immediately, your test is not testing what you think. Delete it and start over. Write the simplest possible code that makes the test pass. Nothing more. **Good implementation:** ```typescript theme={null} function submitForm(data: FormData) { if (!data.email?.trim()) { return { error: 'Email is required' }; } // ... rest of form handling } ``` **Bad implementation** (adding YAGNI options not required by the test): ```typescript theme={null} function submitForm( data: FormData, options?: { strictMode?: boolean; customValidators?: Validator[]; onValidationError?: (err: Error) => void; } ) { // over-engineered before the test demanded it } ``` Run the test again. Confirm it passes. Record the result under `GREEN Evidence`. Only after the test passes: remove duplication, improve names, extract helpers. Never add new behavior during a refactor pass. After every change, run the tests again and confirm they are still green. Record what you cleaned up in the Phase 3 artifact. ## Pragmatic Mode When strict RED-first flow is genuinely infeasible, declare it explicitly. Do not silently skip the process. In the Phase 3 artifact, include: ```markdown theme={null} ## Pragmatic TDD Exception Exception reason: [specific reason strict RED-first flow was not feasible] Compensating validation: - [extra tests, targeted manual verification, diff review, etc.] - `/.recursive/run//evidence/` ``` Evidence files go under `/.recursive/run//evidence/`. ## Phase 3 Artifact Requirements Every Phase 3 artifact must include three sections. ### TDD Compliance Log ```markdown theme={null} ## TDD Compliance Log TDD Mode: strict RED Evidence: - `/.recursive/run//evidence/logs/red/.log` GREEN Evidence: - `/.recursive/run//evidence/logs/green/.log` ### Requirement R1 (Feature X) **Test:** `test/features/x.test.ts` - "should do Y when Z" - RED: [timestamp] - Failed as expected: [output] - GREEN: [timestamp] - Minimal implementation: [description] - REFACTOR: [timestamp] - Cleanups: [description] - Final state: PASS - all tests passing ``` ### Coverage Gate ```markdown theme={null} ## Coverage Gate - [ ] Every new function has a corresponding test - [ ] Every bug fix has a regression test that fails before fix - [ ] All RED phases documented with failure output - [ ] All GREEN phases documented with minimal implementation - [ ] All tests passing (no skipped tests) - [ ] No production code written before failing test TDD Compliance: PASS / FAIL ``` ### Approval Gate ```markdown theme={null} ## Approval Gate - [ ] TDD Compliance: PASS - [ ] Implementation matches Phase 3 plan - [ ] No code without preceding failing test - [ ] All tests documented in TDD Compliance Log Approval: PASS / FAIL ``` ## Red Flags Stop and delete code if you encounter any of these: * Code was written before the test * The test passed immediately (it is not testing what you think) * You planned to add tests later * You described the change as "too simple to test" * You cannot explain why the test failed (or why it didn't fail) * The test asserts mock behavior instead of real behavior * The test name contains "and" (multiple behaviors in one test) ## Common Shortcuts to Reject | Excuse | Why It's Wrong | | ------------------------------------ | --------------------------------------------------------------------------------- | | "This is just a simple fix" | Simple code breaks. The test takes 30 seconds. | | "I'll test after confirming the fix" | Tests passing immediately prove nothing. You never saw the test catch the bug. | | "Tests after achieve the same goals" | Tests-after answer "what does this do?" Tests-first answer "what should this do?" | | "I already manually tested it" | Ad-hoc is not systematic. No record, can't re-run, no regression protection. | | "I need to explore first" | Fine. Throw away the exploration. Start TDD fresh. | # Worktree Source: https://recursive-mode.dev/subskills/recursive-worktree Isolate every recursive-mode run in a dedicated git worktree before implementation begins. ## Overview The `recursive-worktree` subskill protects your main branch by moving all implementation work into an isolated git worktree on a feature branch. Install and run it before Phase 1 of every recursive-mode run. ```bash theme={null} npx skills add try-works/recursive-mode --skill recursive-worktree --full-depth ``` ## When to Use Run this subskill at the very start of every recursive-mode run — before AS-IS analysis and before any planning or implementation phase begins. All subsequent phases, including `STATE.md`, `DECISIONS.md`, and memory updates, stay on the same feature branch until merge time. ## Hard Rule Do not proceed with any recursive-mode phase work until all four conditions are met: 1. A feature-branch worktree exists. 2. The worktree directory is git-ignored (when it lives inside the repo). 3. Project setup has completed successfully. 4. A clean or explicitly acknowledged baseline test state has been recorded. ## Default Worktree Location When choosing where to create the worktree, use this priority order: 1. Existing `.worktrees/` directory in the repo 2. Existing `worktrees/` directory in the repo 3. A preference documented in repo instructions 4. Ask the user 5. Default to `.worktrees/` if none of the above apply **Global fallback:** `~/.config/recursive-mode/worktrees//` ## Creating the Worktree If you are currently on `main` or `master`, create a feature branch worktree automatically: ```bash theme={null} git worktree add .worktrees/ -b recursive/ ``` This creates a new directory at `.worktrees/` checked out on a branch named `recursive/`. All work for the run happens there. If the user explicitly wants to work on `main`, record that exception in `00-worktree.md`. This should be rare. ### Useful Commands Check your current branch before creating the worktree: ```bash theme={null} git branch --show-current ``` Verify the worktree directory is git-ignored: ```bash theme={null} git check-ignore -q .worktrees || git check-ignore -q worktrees ``` ## Project Setup After creating the worktree, run the setup command that matches the repo's toolchain: | Toolchain | Setup Command | | --------- | --------------------------------- | | Node.js | `npm install` | | Rust | `cargo build` | | Python | `pip install -r requirements.txt` | | Go | `go mod download` | | Maven | `mvn compile -q` | | Gradle | `./gradlew compileJava` | | .NET | `dotnet restore` | Then run the project's baseline test command and record the result in `00-worktree.md`. ## Phase 0 Artifact: `00-worktree.md` The artifact lives at `/.recursive/run//00-worktree.md`. It must include all of the following: * Selected worktree location * Git-ignore verification result * Branch name and full worktree path * Setup commands executed and their output * Baseline test command and result * Explicit note that subsequent phases run from the worktree This artifact is the source of truth for the diff basis used by all later phases. Record the baseline reference carefully — downstream phases that calculate diffs depend on what you write here. ## Integration with Later Phases After Phase 0 is complete and lock-valid: * Continue the run from inside the worktree directory. * All phase artifacts go to `/.recursive/run//`. * Later phase diffs compare against the baseline recorded in `00-worktree.md`. * Do not move back to main until the run is fully closed out.