# Make Requirements

> Gather and document requirements, turn an idea into formal requirement documents (RDs). Use for "make_requirements" (full discovery: brain dump or bare idea into a structured requirements/ set), "add_requirement" (add one new RD to an existing set), and "review_requirements" (health check / gap analysis on an existing set). Trigger when the user wants to capture, expand, structure, or audit what a system must do before building it — e.g. "help me spec out my app", "document requirements", "what features am I missing", "add a feature to the requirements", "review my requirements for gaps". Acts as a proactive domain consultant: absorbs the seed idea, expands it with comparable-system features, challenges it with edge cases, then decomposes it into numbered RDs behind a hard Zero-Ambiguity Gate.

- Skill: `blendsdk/make-requirements` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add blendsdk/make-requirements`
- Raw SKILL.md: https://api.skillmd.com/api/skills/blendsdk/make-requirements/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: blendsdk (https://skillmd.com/u/blendsdk)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/blendsdk/make-requirements

---


# Requirements Gathering & Documentation

> **CodeOps Skills Version**: 3.20.0

Transform a rough project idea into a structured, complete set of formal
**requirement documents (RDs)**. This skill is upstream of, and independent
from, the make_plan skill — neither requires the other.

## Core Principle: Proactive Domain Consultant

You are NOT a passive interviewer. You are a **domain-aware consultant** that:

1. **Absorbs** — takes whatever the user provides (brain dump, bullets, vague idea) as seed material
2. **Expands** — draws on knowledge of comparable systems to suggest features the user hasn't considered
3. **Challenges** — asks "what happens when..." to expose edge cases and hidden requirements
4. **Structures** — decomposes the expanded scope into formal, numbered RDs
5. **Validates** — cross-references all documents for gaps, inconsistencies, and missing concerns

The user's input is NEVER the final requirements. The value of this skill is in
**making incomplete ideas complete**.

> **Grounded Options & Recommendations (coding standards → Working style) apply here.** Before presenting options/findings/recommendations: filter out non-viable ones (no strawmen; ≥2 only when ≥2 are genuinely viable, else present the single viable path and name what was rejected), second-guess each, verify any code-modifying option against the actual current code (cite `file:line`), and lead with a recommendation backed by grounded reasoning. Match ceremony to stakes — the user decides. **Recommendation hardening:** apply `_shared/recommendation-hardening.md` — for **high-stakes** Phase 2B gate decisions (complex/sensitive-tagged) spawn one independent challenger and reconcile *before* presenting; for all consequential decisions run the in-context layers and close with the `Confidence:` / `Hardening:` disclosure.

---

## Resolve paths first (layout-aware)

Determine the layout via **[../../_shared/layout-convention.md](../../_shared/layout-convention.md)** before writing anything:

- **Flat layout** (no `codeops/.codeops.yml`): RDs live in `requirements/RD-NN-*.md` with a single
  repo-wide RD sequence — exactly as flat layout always has.
- **Nested layout** (marker present): RDs live in `codeops/features/<f>/requirements/RD-NN-*.md`.
  **Ask/confirm the target feature** before drafting (create the feature folder **lazily** if new
  — never guess the feature). **RD ids reset per feature** (`billing/RD-01` and `auth/RD-01` are
  both valid and independent), and any cross-feature reference is **feature-qualified**
  (`billing/RD-01`). Everywhere below that says `requirements/` means the feature's requirements dir.

## Route first: is this a feature or a task?

Requirements (RDs) are for **features** — new cohesive capabilities. Ad-hoc work (a bugfix,
chore, or small change) is **not** a feature: it is a lightweight **task**, tracked with a
roadmap row (trivial) or a single mini-plan (non-trivial) — **no RD, no discovery, no
Zero-Ambiguity Gate**. The lane exists in **both layouts** (flat gained it in 3.2.0). If the
user's request is really a small fix, route them to the task lane (a roadmap row + `make_plan`
for a non-trivial mini-plan) instead of drafting an RD. If it is genuinely unclear, ask — never
default to the heavy pipeline silently. The task model and routing rule live in
**[../../_shared/layout-convention.md](../../_shared/layout-convention.md)**.

## Step 0: Detect the Mode

Read the user's phrasing and arguments, then branch:

| Signal | Mode | Go to |
|--------|------|-------|
| "make_requirements", "spec out", "document requirements", a brain dump, a bare idea, or nothing but the trigger | **Full Discovery** | Phases 1–4 below |
| "add_requirement", "add a feature/RD", "I also need …" AND a `requirements/` set already exists | **Add One RD** | the `review-and-add.md` reference |
| "review_requirements", "check my requirements", "what's missing/inconsistent" AND a `requirements/` set exists | **Health Check** | the `review-and-add.md` reference |
| "make_requirements --continue" or "resume requirements" | **Resume** | Step 0a |

If a mode is ambiguous (e.g. a `requirements/` folder exists but the user gave a
fresh brain dump), ask the user which they want. Do not guess.

### Step 0a: Resume an interrupted session

If resuming: read `requirements/_draft/discovery-notes.md`, summarize where you
left off (confirmed scope, selected features, open questions, stakeholder map,
which phase/step is next), then continue from the next step.

### Add / Review modes

For **add_requirement** and **review_requirements**, read **`review-and-add.md`**
and follow the protocol there. Both reuse the gate and templates described below.

---

## Step 0b: Classify the domains (before Phase 1 discovery)

Before the first discovery question, classify the system from repository evidence and stated
intent using **[../../references/domains/selection.md](../../references/domains/selection.md)**.
Follow its detect → present → confirm protocol: select every domain whose evidence appears, show
the user the evidence behind each and what was rejected, and let them amend before discovery
proceeds.

The selected domains' question sets join the discovery sweep — they **add** to the universal
ambiguity categories and never replace them. Record the selection and its evidence in the
requirements index, so a later reader can see why a given question set was asked.

This runs for every repository, with or without a quality profile: it dispatches no agent and
emits no telemetry. A `domains:` key in the profile pins the selection and skips detection; it
can never switch classification off.

If discovery later reveals a domain the evidence did not show, surface the change and the
questions it newly requires — never fold it in silently.

## Full Discovery Overview

A multi-turn conversation, never a one-shot. The flow:

```
discovery interview → comparable analysis → user journeys → edge cases →
  scope confirmation → glossary → decomposition → dependency graph →
  🚨 ZERO-AMBIGUITY GATE → RD authoring → validation → final output
```

| Phase | What happens | Reference file |
|-------|--------------|----------------|
| **1. Discovery & Domain Analysis** | Vision interview, stakeholder mapping, comparable-systems analysis, user journeys, edge cases, scope confirmation | **`discovery-phases.md`** |
| **2. Structuring** | Glossary, decompose into RDs, dependency graph, MVP-vs-full phasing, integration map | **`discovery-phases.md`** |
| **2B. Zero-Ambiguity Gate** | Hard, non-negotiable gate — compile the Ambiguity Register, resolve every item with the user | **`zero-ambiguity-gate.md`** |
| **3. Authoring** | Write README + RDs from templates; acceptance-criteria specificity; mandatory non-functional RD | **`templates.md`** |
| **4. Validation** | Cross-reference check, "Did You Consider…" checklist, final verification, roadmap sync, summary | this file (below) + `templates.md` |

### Trigger modes for input (Phase 1 entry)

- **Brain dump** (most common): user gives a rough description with the trigger. Take it as seed material, recognize it's incomplete, enter full discovery.
- **Bare trigger**: nothing but the trigger. Open with the broadest question: *"What do you want to build? Give me as much or as little as you have — a rough idea, some bullet points, a domain, or even just a problem you want to solve."*
- **Existing notes / reference**: user points at files (e.g. "I have notes in docs/project-ideas.md"). Read them, extract the seeds, enter discovery with richer starting material.

---

## The Zero-Ambiguity Rule (active from question one)

This rule applies to **every decision with semantic weight** — feature specs,
behavioral definitions, scope boundaries, edge-case handling, technical choices,
data models, naming, document organization. Behavior/scope/data/security
decisions ALWAYS gate; cosmetic choices with zero semantic impact are exempt
(per the shared gate's traceability exemptions), and low-stakes cosmetic items
may be batched. If you must choose between two or more semantically distinct
options, **the user decides**.

Every question MUST yield a concrete, specific, unambiguous answer. Do NOT accept
vague responses, fill gaps with your own assumptions, infer intent, or proceed
with "reasonable defaults" the user didn't explicitly choose. If an answer is
unclear, ask again with sharper options. If the user says "I'm not sure," lay out
the options with trade-offs and guide them — but the **decision must be theirs**.

Throughout discovery, compile the **Ambiguity Register**. It is formally enforced
at Phase 2B before any RD is written — see **`zero-ambiguity-gate.md`**. The
register is saved permanently at **`requirements/00-ambiguity-register.md`** and
every decision in every RD back-references its AR # entry.

**Telemetry (profile-gated):** when the repo has an active quality profile, emit
`gate_summary` once at the moment the Phase 2B gate PASSES — gate `zero_ambiguity`,
with rounds/questions/decisions/deferrals counts (one `codeops-events.sh emit` call;
an emission failure never blocks the gate).

---

## Phase 4: Validation & Finalization

After all RDs are written:

### 4.1 Cross-Reference Validation

Check for:
- **Missing references** — RD-05 mentions "equipment booking" but RD-07 doesn't list the relationship
- **Orphaned features** — a feature is described but no RD owns it
- **Circular dependencies** — RD-03 → RD-05 → RD-03
- **Scope leaks** — a "Won't Have" in one RD contradicts a "Must Have" in another

### 4.2 "Did You Consider…" Checklist

Run through the commonly-forgotten-requirements checklist (audit logging, data
export, API versioning, rate limiting, empty states, accessibility, backup/DR,
i18n, GDPR/retention, soft vs hard delete, timezones, onboarding, and the
security items below). The full numbered table is in **`templates.md`**.

> **🚨 The security items are NON-NEGOTIABLE** and must be addressed in every
> project: server-side input validation & sanitization; injection prevention
> (SQL, XSS, command, path traversal); auth & authorization model; rate limiting
> on auth/public endpoints; secrets management; encryption at rest and in
> transit; infrastructure hardening; security testing. See your project's
> security coding standards (CLAUDE.md) for the full standard.

### 4.2B Zero-Ambiguity Final Verification 🚨

- [ ] `00-ambiguity-register.md` exists and is saved to disk
- [ ] Every entry has Status = "✅ Resolved" with an explicit user decision
- [ ] Zero deferred items — every ambiguity has a concrete answer
- [ ] All RD decisions carry AR # back-references (only exceptions: universally obvious facts + zero-semantic-impact formatting)
- [ ] No RD contains AI-assumed defaults, inferred behaviors, or guessed specs
- [ ] The surface-during-authoring rule was followed (new ambiguities found while writing went through the register)
- [ ] The user reviewed and confirmed the complete register

### 4.3 Techdocs Update

- **If `docs/index.md` exists with `techdocs: true` frontmatter:** perform an incremental update — extract design decisions from the RDs, create ADRs for every technology/architecture choice affecting behavior, performance, or maintainability, and update architecture sections (see the techdocs skill).
- **If techdocs do NOT exist:** ask the user whether to create technical architecture documentation; if yes, run the techdocs skill using the fresh requirements as input.

### 4.4 Roadmap Sync (RD Drafted)

After each RD is authored (and again at the end of the set):
- **If `plans/00-roadmap.md` exists:** add or sync a row for each newly drafted RD at stage `RD Drafted` (✏️); update its `Stage`, `Status`, `Last Updated`, and the header `Progress` counter, following the update-first mandate.
- **If it does NOT exist:** ask the user whether to create a roadmap. Never auto-create it silently.

See the roadmap skill for the full Roadmap Keeper protocol and stage-transition map.

### 4.5 Final Output Summary

Present the complete set: location (`requirements/`), every document created with
a ✅, and a summary (total RDs, Must/Should/Out-of-scope counts, MVP vs full
product phases). Next step: *"To start implementing, pick an RD and run the
make_plan skill. Suggested order: RD-01 → RD-02 → …"*

---

## Session Management (long conversations)

Requirements gathering is long and multi-turn. RD documents and the Ambiguity
Register are **written to disk as they are completed** — never held only in
conversation memory, so they survive an interrupted session.

**Save progress and resume natively:**
- If the session is getting long or the user wants to pause, save all progress to `requirements/_draft/discovery-notes.md` (confirmed scope, selected features, open questions, stakeholder map, and which phase/step to resume from). Save any completed RDs to `requirements/` and any in-progress RD to `requirements/_draft/`.
- The user resumes later by saying "make_requirements --continue" (or "resume requirements"). On resume, read the draft notes and any existing RDs, summarize the state, and continue from the next step.

---

## Adapting to Project Type

Tailor discovery questions and comparable-systems analysis to the project type
(SaaS, internal tool, API/backend, library/SDK, CLI, mobile, e-commerce, CMS,
healthcare, education, fintech, …). The full mapping of project type →
comparable systems → key discovery focus is in **`discovery-phases.md`**.

## Related Skills

- the make_plan skill — how RDs feed into implementation plans (downstream)
- the grill_me skill — deep disambiguation before requirements gathering (grill_me → make_requirements)
- the techdocs skill — technical architecture documentation from design decisions
- the upgrade_plan skill — upgrading outdated requirements (upgrade_requirements)
- the roadmap skill — sync each newly drafted RD to stage `RD Drafted`
- Read the project's CLAUDE.md (or detected project conventions) for project-specific constraints

## Authority mode — `--auto-design` (optional)

`--auto-design` delegates **eligible technical** design decisions for this workflow chain, so a run
stops for product, security, financial, legal, and destructive choices — not for a data-structure
pick. The complete policy (invocation contract, eligibility boundary, reserved list,
strongest-option procedure, provenance record, bounded escalation, invalidation) lives in
**[../../_shared/auto-design.md](../../_shared/auto-design.md)** and is deliberately not restated
here.

**Parse it FIRST, before resolving any target.** Exactly one standalone `--auto-design` token
before the first `--` sentinel activates the mode and is then **removed** from the arguments;
zero occurrences means normal mode; more than one stops with a usage correction. Lookalikes
(`--auto-designer`, `--auto-design=true`, bare `auto-design`) and anything at or after the
sentinel are ordinary content. Announce activation in-session before making any delegated
decision.

It grants **no action permission** and is independent of the commit mode. Every delegated
resolution carries the full provenance record into the artifact that owns the decision.