recursive-spec

name	recursive-spec
description	Approval-gated, repo-aware requirements/spec authoring for new recursive-mode runs. Use when the user wants help creating a plan, spec, scope, or requirements for work that does not yet have a run, especially prompts like "create a plan", "help me plan", "create a spec", "write requirements", or similar derivatives.

recursive-spec

Use this skill to co-author a repo-aware 00-requirements.md for a new recursive-mode run.

This skill is for requirements/spec authoring before implementation starts. It does not replace /.recursive/RECURSIVE.md, and it should not skip ahead to Phase 2 planning or Phase 3 implementation.

Primary Use Case

Use recursive-spec when the user wants help shaping work before a run exists, especially with prompts like:

• create a plan
• help me plan
• create a spec
• write requirements
• spec this out
• scope this

The important signal is plan/spec language for a new run, not implementation of an existing run.

Conversation Contract

When the trigger is detected:

1. First ask whether the user wants help creating a spec for a recursive run.
2. If the user replies positively, ask: What do you want to do?
3. Then gather context, read the repo, and co-author the requirements.

Do not jump straight into writing 00-requirements.md before the user confirms they want spec help.

Draft Handling Before Approval

Until the user explicitly approves the spec:

• keep the draft outside the repository worktree
• prefer a temporary session artifact or scratch file
• do not create /.recursive/run/<run-id>/
• do not write 00-requirements.md

If the user rejects the draft, revise it or discard the temporary draft artifact. Do not leave behind a half-approved run folder.

Required Read Behavior

Before drafting requirements, read:

1. /.recursive/STATE.md
2. /.recursive/DECISIONS.md
3. /.recursive/memory/MEMORY.md
4. relevant memory shards only when they actually matter
5. the most relevant code and tests for the requested area

The skill should be repo-aware, not a blind questionnaire. Use the control-plane docs to understand current truth and the codebase to understand actual surfaces, coupled modules, existing tests, and likely boundaries.

Authoring Flow

Use a guided interview. Ask one focused question at a time when the answer is not already grounded by repo docs or code.

Recommended sequence:

1. Goal and user outcome
2. Task type: feature, bugfix, refactor, migration, investigation
3. Affected subsystem or files
4. In-scope requirements (R#)
5. Observable acceptance criteria for each requirement
6. Edge cases, failure paths, and exclusions
7. Constraints, fixed decisions, and boundaries
8. Open unknowns that must be resolved before Phase 0 is locked

Prefer proposing draft wording and asking the user to confirm or correct it rather than asking the user to author the whole document from scratch.

Quality Rules

Borrow the strongest authoring ideas from contract-first workflows, but keep the output native to recursive-mode:

• start with user intent and desired outcome
• separate fixed decisions from open questions
• define deterministic, observable acceptance criteria
• include exception and failure-path thinking instead of only the happy path
• make boundaries concrete enough to guide later AS-IS analysis and planning
• keep out-of-scope items explicit

Do not introduce a separate .spec DSL or a second workflow format.

Output Contract

The finished output should become:

• /.recursive/run/<run-id>/00-requirements.md

Use the repository's native Phase 0 requirements structure:

• keep the scaffolded header from recursive-init, including Workflow version: recursive-mode-audit-v2
• keep the required ## TODO section and replace placeholder checklist items rather than deleting the heading
• ## Requirements
• ## Out of Scope
• ## Constraints

Within ## Requirements, each R# should include:

• a short title
• a clear description
• observable acceptance criteria bullets

Run Creation Rule

Do not create the run folder immediately.

1. Draft and refine the requirements with the user first.
2. Keep the draft in a temporary non-repo artifact until approval.
3. Confirm the user approves the spec and that it is complete enough to proceed.
4. Create the run with scripts/recursive-init.py or scripts/recursive-init.ps1.
5. Replace the scaffolded 00-requirements.md with the approved requirements content.

This keeps the run artifact grounded in user-approved requirements instead of half-formed notes.

Routing Awareness

If spec authoring uses delegated critique, delegated review, or any other external model help to shape the draft, re-read:

• /.recursive/config/recursive-router.json
• /.recursive/config/recursive-router-discovered.json

immediately before choosing that CLI/model, and route through recursive-router instead of inventing an ad hoc model choice.

Boundaries

• Stay focused on 00-requirements.md authoring for a new run.
• Do not silently convert this into Phase 2 planning.
• Do not start implementation just because the requirements became clear.
• Do not skip code reading when repository structure matters to scope or constraints.
• Do not create a run until the user-approved spec is ready to write.
• Do not write repository requirements artifacts from an unapproved draft.

References

• /.recursive/RECURSIVE.md
• /.recursive/STATE.md
• /.recursive/DECISIONS.md
• /.recursive/memory/MEMORY.md
• ../../references/artifact-template.md
• ./references/patterns.md