Skip to content

skill · phase: requirements

Adversarial Review

Purpose

Provide a structured, critical review of a lifecycle artifact from fresh context. Surface ambiguities, contradictions, missing edge cases, and risks before the artifact drives downstream work.

{{glossary:artifact}}

Important

You MUST perform this review with fresh eyes. If you authored the artifact being reviewed, delegate to a separate session or subagent. Self-review defeats the purpose.

Entry Criteria

  • A target artifact exists (requirements.md, design.md, or other phase artifact)
  • The reviewer is a different session/agent than the artifact author

Required Artifacts

  • <artifact>.review.md — Structured findings file in the instance namespace, where <artifact> includes the artifact's own .md. The findings file for requirements.md is requirements.md.review.md, with the extension twice. The doubled .md looks like a typo and is not: the gate looks artifacts up by the name the template declares, so requirements.review.md is a file the gate cannot see. aidlc review <instance> requirements and aidlc review <instance> requirements.md both write the correct name, so prefer the command over hand-naming the file.

Write one findings file per required artifact of the phase under review. The phase's required artifacts are listed in phase-<name>.yaml in the instance directory — read them from there rather than from a list in this skill, because they vary per template and a project may override a template under .aidlc/templates/.

This is what the review gate checks: it looks for a findings file for each required artifact of the gated phase, so a phase with two required artifacts needs two files. Optional artifacts are yours to judge — the gate does not ask about them.

The split is also the better review. Reviewing design.md and tasks.md into one pooled file lets a finding about one hide behind the other; separating them forced agent-portability's findings about its architecture diagram apart from its findings about the design, and two of those turned out to be real defects that the pooled form had obscured.

Instructions

  1. Read the target artifact completely. Do not skim.

    • When the phase requires a tasks.md as well as a design.md, review the breakdown with the design in hand — breakdown completeness (every design section covered by a task), task sizing (commit-sized units), and AC linkage (tasks reference the criteria they satisfy) are all judgements about the design/breakdown pair, not about tasks.md alone. Read both, then record the breakdown's findings in its own findings file.

  2. Load guidance. 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.

  3. Check for installed compliance controls. Run aidlc compliance list. If nothing is installed, skip this step and the compliance findings stream below entirely — there is nothing to check and no file to write. If a pack is installed, run aidlc compliance check to get the controls that apply to this phase, each with what it requires, where to look, and its fail condition. Apply those fail conditions as written: they are the pack's, and reinterpreting one turns a stated control into your opinion.

  4. Examine for each dimension:

    • Ambiguities — Vague terms, undefined behavior, unclear scope
    • Contradictions — Requirements that conflict with each other
    • Missing edge cases — Inputs, states, or scenarios not addressed
    • Untestable criteria — Requirements with no observable pass/fail
    • Hidden assumptions — Unstated preconditions the artifact relies on
    • Security gaps — Missing auth, unvalidated input, exposed data. When the instance has implementation code (a branch or diff), review the CODE for this dimension, not only the markdown artifacts: injection sinks (shell, SQL, path, template), secrets in source, missing authorization checks, and unsafe deserialization. Apply the secure-defaults guidance below as the checklist.
    • Scalability concerns — Performance bottlenecks or resource limits
    • Scope creep — Functionality beyond the stated scope

  5. Write findings. For each issue found, record:

    • Severity: critical, major, or minor
    • Section: The specific part of the artifact
    • Issue: Clear description of the problem
    • Suggestion: A concrete resolution or question to ask
    • Status: open (always for new findings)

  6. Save the findings file as <artifact>.review.md in the instance namespace — one per required artifact, per Required Artifacts above.

  7. Write the compliance findings stream, only when a pack is installed. It is a separate file: <artifact>.compliance.md, never mixed into <artifact>.review.md. The separation is load-bearing — the phase transition gate reads only *.review.md, so keeping control findings out of it is what lets them be advisory by default. See "Compliance Findings Format" below.

    Every applicable control must appear in exactly one of two places, or it counts as unchecked:

    • a finding block carrying its Control id, when the fail condition is met;
    • a line in ## Controls Checked reading - **Control:** <id> — no issues, when you looked and found nothing.

    Do not write a cleared line for a control you did not actually examine. An unchecked control reported as covered is the one outcome worse than no check at all.

{{guidance:secure-defaults}}

Findings Format

---
artifact: <filename>
reviewed_at: <ISO 8601 UTC>
reviewer: <session-id>
---

## Finding 1
- **Severity:** critical | major | minor
- **Section:** <section reference>
- **Issue:** <description>
- **Suggestion:** <resolution>
- **Status:** open

Compliance Findings Format

Only written when a compliance pack is installed. File: <artifact>.compliance.md.

---
artifact: <filename>
reviewed_at: <ISO 8601 UTC>
reviewer: <session-id>
---

## Finding 1
- **Control:** <control id from the pack>
- **Severity:** critical | major | minor
- **Section:** <where in the artifact or diff>
- **Issue:** <how the fail condition is met>
- **Suggestion:** <what would satisfy the control>
- **Status:** open

## Controls Checked
- **Control:** <control id> — no issues
- **Control:** <control id> — no issues

The Control bullet is what links a finding to a control. A finding without one satisfies nothing, and a control appearing in neither section counts as unchecked.

Exit Criteria

  • A findings file exists in the instance namespace for every required artifact of the phase under review, as listed in phase-<name>.yaml
  • Every dimension was considered (even if no issues found — state "no issues" for that dimension)
  • Findings are actionable (each has a concrete suggestion or question)
  • When a compliance pack is installed: <artifact>.compliance.md exists and every applicable control appears either as a finding carrying its id or as a cleared line

Review Gate

{{glossary:gate}}

When a workflow template configures an adversarial review gate for a phase, the phase transition is blocked until:

  • A findings file exists for the phase's required artifacts
  • No finding with severity critical has status open

Security Confirmation

If the review identifies security vulnerabilities:

  1. Flag them as critical severity
  2. Note that these MUST be resolved before deployment
  3. If the vulnerability involves exposed credentials or active exploits, alert the user immediately rather than only recording a finding

Completion

After writing the findings file, report the review summary: total findings count by severity, and whether any critical findings block phase transition.