Skip to content

skill · phase: requirements

Requirements Phase

Purpose

Translate the ideation output (or the user's direct request) into precise, testable acceptance criteria.

Entry Criteria

{{glossary:scope}}

  • Ideation phase complete (Full scope) OR instance created with Standard scope
  • The instance is claimed by this session

Entering in a fresh session

Read only:

  • instance.yaml
  • the ideation artifact (idea.md, or research-question.md for spike) — Full scope only
  • the roadmap item this instance was promoted from — Standard scope, where it replaces the ideation artifact as input
  • the always-read guidance layers named in .aidlc/guidance/index.yaml (see The always-read rule in aidlc-overview)
  • .aidlc/context/constitution.md, when it exists

Not the ideation conversation — the artifact is what it was written for. See The context rule in aidlc-overview.

Required Artifacts

  • requirements.md — User stories, acceptance criteria, scope boundaries, non-functional requirements

Instructions

{{glossary:artifact}}

  1. Gather requirements. If a Full scope, read the ideation phase's artifact for context (idea.md for the feature templates, research-question.md for spike; phase-ideation.yaml names it). Otherwise, ask the user to describe desired behavior. Read the always-read guidance layers from .aidlc/guidance/index.yaml — see The always-read rule in aidlc-overview for which layers those are and when to reach for the full lessons.md. Read .aidlc/context/constitution.md when it exists and apply the constitution rule in aidlc-overview.
  2. Write user stories. Use the format: "As a [role], I want [capability], so that [benefit]."
  3. Define acceptance criteria. Each criterion must be:
    • Specific and unambiguous
    • Testable (an observable outcome)
    • Independent (not relying on unstated assumptions)
    • Identified: write every criterion as a list item - AC-<n>: <text> (bold variants - **AC-<n>**: ... and - **AC-<n>:** ... are also valid). Assign AC-1, AC-2, ... sequentially. IDs are never renumbered or reused — an amended criterion keeps its meaning or is retired: mark it - AC-<n> (retired YYYY-MM-DD, superseded by AC-<m>): <text> and issue a new ID. The testing-phase gate parses these IDs and fails on any active criterion without a referencing test.
  4. Set scope boundaries. Explicitly state what is NOT included.
  5. Non-functional requirements. Address performance, security, accessibility, and compatibility where relevant.
  6. For open decisions: When a decision would change what requirements.md says, ask it through the Question Protocol in aidlc-overview — questions for this phase go to .aidlc/state/<instance>/requirements-questions.md. Prefer drafting requirements.md early with the unresolved points marked as explicit decision blocks: users decide better reacting to a concrete draft than answering abstract questions. Fold each answer into the draft and leave the question file as the record of what was decided and why.

Bugfix Reproduction (bugfix template)

When the instance uses the bugfix template, this phase produces reproduction.md instead of full requirements:

  1. Reproduce first. Capture: observed behavior, expected behavior, minimal reproduction steps, affected versions/environment. A bug that cannot be reproduced gets documented as such — with the evidence tried — before any fix work.
  2. Acceptance criteria for the fix follow the same AC-<n> ID rules as regular requirements (the reproduction steps typically become the test).
  3. Propose defect linkage (caused_by). Identify which instance(s) likely introduced the defect:
    • git blame the defective lines and match commits to instance branches (fix|feat|chore/<YYYYMMDD>-<name>)
    • Query the knowledge graph for the module's history
    • Check instance state dirs and the registry for names Present the candidates as guesses with the evidence. The user confirms, edits, or declines — caused_by is never written without explicit user confirmation, and declining leaves the field absent (absent = unknown, never an error).
  4. Write the confirmed linkage to instance.yaml as a list: caused_by: [<instance>, ...] (single cause = one-element list). Validate every name against existing state dirs or registry entries — an unknown name needs re-confirmation; reject the bugfix's own name (no self-reference).

Exit Criteria

  • requirements.md exists with at least one user story and corresponding acceptance criteria
  • Each acceptance criterion is testable (has an observable pass/fail condition)
  • The user has confirmed the requirements are complete for the chosen scope

Guidance

{{context:style-guide}} {{guidance:secure-defaults}}

Security Confirmation

If requirements reference sensitive data handling, authentication flows, or access control:

  1. Explicitly document the security requirements as acceptance criteria
  2. Flag that a security review will be needed before deployment
  3. Never embed credentials or secrets in requirement examples

Completion

When exit criteria are met, update phase-requirements.yaml status to complete and append a transition record to transitions.log.

Amending a Completed Phase

A completed phase's artifact is changed only through an amendment. Editing requirements.md after its phase closed leaves phase-requirements.yaml saying complete, leaves the design and the code describing the old criterion, and leaves every gate passing — because gates check that artifacts exist, not that they still agree with each other. That is silent drift, and it is the most common real-world mess in any lifecycle.

To change a criterion after its phase closed:

  1. Edit the definition bullet in place into the retired form — - AC-<n> (retired YYYY-MM-DD, superseded by AC-<m>): <one-line summary of what it said> — and add the replacement as a new criterion with a fresh ID. IDs are never renumbered or reused.

  2. Append an amendment section to requirements.md:

    ## Amendment 1 — 2026-09-07, after the design review
- **Retires:** AC-4, AC-9
- **Issues:** AC-31
- **Reopens:** design
- **Reason:** the customer integration needs JSON as well as CSV

    Field bullets accept Retires:, **Retires**: and **Retires:** alike. AC lists take whole AC-<n> tokens only — AC-4..AC-6 is not a range and contributes nothing. A wrapped bullet is still one bullet.

  3. Run aidlc amend <instance> --impact to see which tasks, tests and artifacts still cite the retired criteria. The walk is advisory: it suggests phases, it does not choose them.

  4. Put the phases you actually want reopened in Reopens:, then run aidlc amend <instance>. It reopens that phase and every phase between it and the current one, re-arming their gates, and records a type: reopen entry in transitions.log so the churn is visible in history rather than reading as a normal forward pass. From testing onwards it requires --confirm.

Amendments append; the definition bullet's status changes. Never rewrite an amendment that has already been applied — write the next one.