# Requirements > Capture and document requirements for implementation. Triggers on "capture requirements", "document requirements", "what do I want to build", or feature discussions without clear documentation. Produces requirements.md artifact for design and planning phases. - Skill: `ddaanet/requirements` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add ddaanet/requirements` - Raw SKILL.md: https://api.skillmd.com/api/skills/ddaanet/requirements/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Docs & Writing - Author: ddaanet (https://skillmd.com/u/ddaanet) - Updated: 2026-09-10 - Page: https://skillmd.com/skills/ddaanet/requirements --- # Capture Requirements Dual-mode requirements capture: extract from conversation or elicit through semi-structured questions. Produces `plans//requirements.md` artifact consumed by `/design` and `/runbook`. ## Target Model **Opus required.** Extract mode requires synthesizing nuanced conversation context; sonnet misses implicit requirements. ## Usage ``` /requirements ``` Skill automatically detects appropriate mode based on conversation history. ## Mode Detection **Primary signal:** `Glob: plans//requirements.md` — if file exists, Read it and use as base for update/refinement (extract mode with existing artifact). If absent, fall through to conversation heuristic. **Conversation heuristic (fallback):** - **Extract mode** — conversation contains substantive discussion (feature descriptions, constraints, scope) - **Elicit mode** — fresh conversation or minimal context (no prior feature discussion, cold-start) ## Recall Pass **Runs after mode detection, before either procedure.** Ground extraction in existing infrastructure, patterns, and decisions — prevents naive requirements. ### Process Invoke `/recall all` (deep + broad, topic-scoped). This is a skill invocation — `/recall` handles memory-index scanning, batch resolution, and tail-recursion. Derive topic from job name, conversation context, and any existing `plans//` artifacts. **Gate anchor:** The `/recall all` Skill invocation is the structural anchor — a tool call on both paths. When no relevant entries are found, write the recall artifact with an explicit null entry (see format below). Downstream consumers batch-resolve it via `edify _recall resolve null` — the tool call fires on both paths without consumer-side conditional logic. **Boundaries:** - No agent delegation, no Context7, no web research — those belong to /design A.1 - Purpose: ground the extraction, not exhaustive documentation loading ### Recall Artifact After recall completes, write `plans//recall-artifact.md`. Entry keys only — downstream consumers resolve fresh content at consumption time. **Format:** ```markdown # Recall Artifact: Resolve entries via `edify _recall resolve` — do not use inline summaries. ## Entry Keys — <1-line relevance note> — <1-line relevance note> ``` **Null artifact (no relevant entries):** Write `null — no relevant entries found` as the sole entry. Downstream consumers batch-resolve it via `edify _recall resolve null` (silent exit) — the tool call anchors the gate without consumer-side empty-section handling. Augmenting consumers (/design A.1, /runbook Phase 0.5) remove the null entry when adding real ones. **Selection criteria:** Include entries that informed requirements or constrain implementation. Exclude entries read but proved irrelevant — the artifact is curated, not exhaustive. **Output:** `plans//recall-artifact.md` ## Extract Mode Procedure When conversation contains requirements signals: ### 1. Scan Conversation Extract from conversation history: - **Functional requirements:** What should the system do? - **Non-functional requirements:** Performance, usability, constraints - **Explicit constraints:** Technology, compatibility, architecture - **Scope boundaries:** What's in vs out of scope - **Dependencies:** Blocking work, prerequisites - **Open questions:** Unresolved items mentioned **Critical rule:** Extract from what was said, do NOT infer unstated requirements. Hallucination risk — if not discussed, flag as Open Question rather than inventing. ### 2. Lightweight Codebase Discovery Quick scan to ground requirements (runs after extraction, so scan is targeted): **Discovery actions** (guideline: ~5 tool calls, flexible based on complexity): 1. `Glob` for `plans/*/requirements.md` and `plans/*/design.md` — find related work 2. `Grep` for key terms from extracted requirements — check what exists 3. `Read` existing patterns in relevant area — inform constraints **Boundaries:** - Direct tool use only (Glob, Grep, Read, Bash, Write) - No agent delegation - No Context7, no web research, no scout - Purpose: prevent naive requirements (e.g., "add X" when X exists) - Tool count is a guideline, not a hard limit — use judgment for complex domains - Save exploration prototypes to `plans/prototypes/` (not `tmp/`) — they are referenced artifacts, not ephemera ### Post-Explore Recall Gate Discovery via Glob/Grep may surface domains not anticipated during the initial recall pass. Re-scan memory-index (already in context from recall pass) for entries relevant to areas discovered during codebase exploration. **Gate anchor (D+B — tool call required):** - **New entries found:** `edify _recall resolve "when " ...` — resolve into context, update recall artifact with new entry keys - **No new entries:** `edify _recall resolve null` — proves gate was reached ### 3. Structure Requirements Format into standard artifact (see Standard Format section below): - Number items sequentially within each section (FR-1, FR-2, ...) - Include acceptance criteria for functional requirements - Capture rationale for constraints - Omit empty sections entirely ### 4. Gap Detection Check for empty critical sections: **Critical sections** (ask if empty): - Functional Requirements — "What should the system do?" - Out of Scope — "What should it NOT do?" **Non-critical sections** (note absence, don't ask): - NFRs, Constraints, Dependencies — many tasks genuinely have none **Question budget (applies to both Extract and Elicit modes):** - Extract mode: Maximum 3 gap-fill questions for empty critical sections - Elicit mode: 4-6 total questions (section questions + adaptive follow-ups) Use `AskUserQuestion` tool for gap-fill: ``` questions: [ { question: "What should the system do? (Functional requirements)", header: "Functional", options: [ // Generate context-relevant options from job name and conversation // Example for job "git-hook-validator": {label: "Validate hook scripts before commit", description: "Parse and check hooks for common errors"}, {label: "Block commits with invalid hooks", description: "Fail commit if hooks malformed"}, {label: "Report hook validation errors", description: "Show clear error messages for failures"}, ... ], multiSelect: true } ] ``` ### 5. User Validation Invoke `/proof plans//requirements.md` — structured reword-accumulate-sync loop on the requirements draft. Present artifact path, summarize sections populated, note Open Questions. /proof handles the iterative validation loop. No corrector dispatch for requirements (user-validated directly). On terminal action "apply", accumulated decisions are applied to the artifact. ### 6. Write Artifact After user validation: - Write to `plans//requirements.md` (create directory if needed) - Scan for skill dependencies (see Skill Dependency Scanning section) - Suggest next step (see Default Exit section) ## Elicit Mode Procedure When conversation lacks requirements context: ### 1. Semi-Structured Elicitation Use `AskUserQuestion` for each critical section (Functional Requirements, Scope Boundaries) with domain-relevant options. Add optional Constraints/Dependencies questions if job suggests them. Adaptive follow-ups: 1-2 clarifying questions based on responses. Total budget: 4-6 questions. ### 2-6. Shared Steps After elicitation, follow Extract mode steps 2-6 (Codebase Discovery, Structure, Gap Detection, Present Draft, Write Artifact). ## Standard Format ```markdown # ## Requirements ### Functional Requirements **FR-1: ** **FR-2: ** ### Non-Functional Requirements **NFR-1: ** ### Constraints **C-1: ** ### Out of Scope - — ### Dependencies - — ### Open Questions - Q-1: ### References - `plans//reports/explore-.md` — codebase exploration findings - `plans/reports/.md` — grounding research synthesis - [External Paper Title](url) — informed FR-2 scope decision ``` **Section rules:** - Omit empty sections entirely (don't scaffold structure) - Number identifiers sequentially within each section (FR-1, FR-2, ... not FR-1, FR-3) - Open Questions captures items conversation didn't resolve → become Design Phase A research targets - Dependencies flags blocking work, prerequisite plans, or external dependencies - References track provenance — what research, external sources, or project artifacts informed the requirements. Include exploration reports, grounding research, external papers, prior plan reports. Omit if requirements came entirely from conversation. ## Skill Dependency Scanning After writing artifact, scan requirements text for skill dependency indicators: | Indicator | Skill to Flag | |-----------|---------------| | "sub-agent", "delegate to agent", "agent definition" | `plugin-dev:agent-development` | | "skill", "invoke skill", "skill preloaded" | `plugin-dev:skill-development` | | "hook", "PreToolUse", "PostToolUse" | `plugin-dev:hook-development` | | "plugin", "MCP server" | `plugin-dev:plugin-structure` | If indicators found, append to artifact: ```markdown ### Skill Dependencies (for /design) - Load `plugin-dev:hook-development` before design (hooks mentioned in FR-2) ``` **Rationale:** Artifact-scoped scanning reduces A.0 scan time — planner reads requirements.md first, loads indicated skills immediately rather than scanning entire codebase. ## Default Exit Present artifact path and suggest next step based on completeness: ``` Requirements written to: plans//requirements.md Next steps (decision criteria): - 0-2 open questions, all critical sections populated → `/design plans//` - 3+ open questions or empty critical sections → Standalone (revisit when clearer) - Very clear scope + simple (Tier 1/2) → `/runbook plans//requirements.md` - User stated explicit next step → Use that path ``` **Workflow positioning:** ``` /requirements → /design plans// (seeds A.0) /requirements → /handoff (document intent for later) /requirements → /runbook plans//requirements.md (direct to planning) /requirements (standalone — capture intent, no immediate follow-up) ``` ## Key Principles - Extract from conversation, do not infer (hallucination risk) - Gap-fill, not interrogation: max 3 questions (extract) or 4-6 (elicit) - Omit empty sections — do not scaffold structure nobody will fill - See `references/empirical-grounding.md` for research basis