requirements-doc

name	requirements-doc
description	Generate a structured requirements document from unstructured plans or ideas. Use when the user describes a system they want to build and needs formal requirements.
argument-hint	[prefix] [description of what to build]

Generate a structured requirements document from the user's unstructured description through an interactive discovery process.

Input

The user will provide: $ARGUMENTS

$ARGUMENTS may contain a design prefix followed by a description. The prefix allows multiple designs to coexist in the same project (e.g., client-requirements.md and server-requirements.md). The naming pattern is {prefix}-requirements.md.

Example: client A REST API for managing clients — here client is the prefix and A REST API for managing clients is the description.

If no arguments provided, ask the user to describe what they want to build.

Expected Folder Structure

design/
└── {prefix}-requirements.md    # Output: e.g., client-requirements.md

Process

Phase 1: Discovery & Clarification

First, analyze the input and identify gaps. Ask follow-up questions to fill in missing details. Use AskUserQuestion to gather information in these categories:

Entities & Data

• What are the core entities/objects in the system?
• What are the relationships between them (one-to-many, many-to-many)?
• What key attributes does each entity have?

Behaviors & Workflows

• What are the main actions users/systems can perform?
• Are there state transitions or lifecycles to track?
• What triggers these actions (user input, schedules, events)?

APIs & Interfaces

• Is this API-first, UI-first, or both?
• What operations need to be exposed (CRUD, custom actions)?
• Are there external systems to integrate with?

Configuration & Flexibility

• What should be configurable vs hardcoded?
• Are there system-wide defaults that can be overridden per-entity?
• What are sensible defaults?

Error Handling & Edge Cases

• What happens when things fail?
• Are there timeout/retry considerations?
• What health checks or monitoring are needed?

Scope Boundaries

• What's explicitly NOT in scope for v1?
• Are there future features to design for but not implement?

Ask 2-4 focused questions at a time using AskUserQuestion. Provide reasonable default options where possible. Continue until you have enough clarity to write comprehensive requirements.

Phase 1.5: Determine Design Prefix

Determine the design prefix from $ARGUMENTS:

• If $ARGUMENTS starts with a single short word (no spaces) followed by more text, treat the first word as the prefix and the rest as the description. For example, client A REST API for managing clients has prefix client.
• If $ARGUMENTS is just a description with no obvious prefix, ask the user: "What design prefix should be used? This allows multiple designs to coexist in the same project (e.g., 'client', 'server', 'auth')."

Store the prefix for use in file naming throughout the remaining phases.

Phase 2: Document Generation

Once you have sufficient information:

1. Extract and organize:

   • Core concepts and terminology
   • Entities and their relationships
   • Functional requirements grouped by feature area
   • API endpoints needed
   • Configuration parameters
   • Non-functional requirements
   • What's out of scope

2. Create design/{prefix}-requirements.md using the template in template.md

3. Include Mermaid diagrams where they add clarity:

   • erDiagram for entity relationships
   • stateDiagram-v2 for state machines/lifecycles
   • flowchart for processes and decisions
   • sequenceDiagram for API interactions

4. Mermaid Diagram Rules (required for renderer compatibility — GitLab, GitHub, VS Code use older Mermaid.js):

   • Always quote flowchart node labels: A["Start here"] not A[Start here]
   • Always quote decision nodes: B{"Is it ready?"} not B{Is it ready?}
   • Always quote subgraph titles: subgraph sg["My Group"] not subgraph sg[My Group]
   • Prefer A -- "label" --> B link syntax over A -->|"label"| B
   • Use plain text participant aliases in sequence diagrams: participant SVC as my-service
   • Keep labels short — move detail into surrounding prose
   • NO <br/> in any label or node text
   • NO par / and blocks in sequence diagrams — use Note over A,B: description instead
   • NO <--> bidirectional arrows — use two separate directed arrows
   • NO }o--|| at start of erDiagram lines — reverse to ||--o{
   • NO special characters in state/flowchart labels: () . / → __ — use plain words

5. Conventions:

   • Use requirement IDs (e.g., FR-3.1.1) for traceability
   • Use RFC 2119 language (SHALL, SHOULD, MAY, MUST)
   • Tables for structured data (endpoints, config, states)
   • Document any assumptions made

Phase 3: Sync to Grimoire

After writing the local file, sync it to the grimoire so it's searchable and accessible across projects.

1. Derive the project name from the project context:

   • Check design/{prefix}-requirements.md title or the project's root directory name
   • Use a short, lowercase, hyphenated name (e.g., my-api-server, data-pipeline)
   • If unclear, use AskUserQuestion to ask the user what to call this project

2. Write the file to the grimoire:

   ~/.grimoire/files/technical-designs/{project-name}/{prefix}-requirements.md
   

   Copy the full contents of design/{prefix}-requirements.md to this path.

3. Register metadata using the grimoire-cli CLI:

   grimoire-cli create-file-metadata \
     --file "files/technical-designs/{project-name}/{prefix}-requirements.md" \
     --source-agent "requirements-doc" \
     --tags "type/requirements,project/{project-name},topic/technical-design" \
     --summary "Requirements document for {project name}"
   

   If the file already exists in the grimoire, use update-file-metadata instead.

4. If the grimoire CLI is not available (command not found), skip this phase silently — the local file is the primary output.

Output

Create design/{prefix}-requirements.md (create design/ directory if needed). Also synced to ~/.grimoire/files/technical-designs/{project-name}/{prefix}-requirements.md if the grimoire is available.