j-analyze-requirements

name	j-analyze-requirements
description	Decompose the task instruction into an exhaustive list of atomic, independently-testable requirements BEFORE planning. Surfaces buried/secondary clauses that all-or-nothing graders punish.

Requirements Analyst Mindset

Why this step exists

Graded tasks are all-or-nothing: one unmet requirement fails the whole task even when everything else is correct. The recurring failure mode is NOT bad logic — it is a missed requirement, usually a secondary clause buried inside a compound sentence (e.g. "X must be disabled while in state S and the related view must reflect the same state and leaving S must restore it" — that is three separate requirements). When you extract requirements while also designing the plan, these clauses slip. This step forces you to enumerate EVERY atomic requirement first, with full attention, before any implementation design.

The product is requirements.md — a flat, numbered list the planner and the plan review both map against.

Steps

1. Read the task

• Read instruction.md in full. Read it twice.
• If memory-bank/ exists, read it for project context (do not re-derive).

2. Decompose into ATOMIC requirements

• Split EVERY compound sentence into separate items. Clauses joined by and, ,, ;, including, as well as, must also, but are usually SEPARATE requirements.
• One requirement = ONE independently-testable claim. If a single test cannot prove it on its own, split further.
• Do NOT paraphrase away specifics. Keep exact field names, header names, enum values, types, units, counts, and exact strings from the instruction.

3. Hunt the easy-to-miss kinds (checklist — apply to EVERY sentence)

For each sentence, ask whether it also implies any of these, and if so emit a separate item:

• Negative / "must not" — must not duplicate, must not move focus, must not apply formatting.
• State-dependent — disabled / read-only / empty / before-first-use / after-removal states.
• Restore / reversal — switching back, re-enabling, undo, re-adding restores prior behavior.
• Cardinality — exactly once, exactly one, no duplicates, at most/at least N.
• Exact shape — response/JSON keys, field order, exact types & units (int vs float, ms), exact header/enum strings, RFC formats.
• Lifecycle — init, re-init, recreation, teardown, add-after-init, remove-then-readd.
• Targeting — applies to the active/current one, not a stale or previous one.

3b. Surface / entity inventory — expand category-ranging requirements to EACH member

Many requirements quantify over a CATEGORY rather than one thing — e.g. "the controls", "public callables", "endpoints", "form fields", "UI elements", "response fields". The recurring miss is satisfying the requirement for SOME members of the category but not all — especially members with different mechanics. For every such requirement:

1. ENUMERATE the concrete members of the category FROM THE CODEBASE (read the actual code/markup — do not guess). E.g. every interactive control in scope (each button, each dropdown/select, each file input, each text field), or every public function the task names, or every endpoint.
2. Note which members have DIFFERENT mechanics for this requirement — a native form control, a custom dropdown/picker, a file input, and a plain element each express/handle a state differently. These differences are exactly where coverage is lost.
3. Emit the requirement's accept: so it covers EACH member explicitly (or split into one R per member when their mechanics differ enough to need separate tests). A representative subset is NOT enough — "applies to controls" means EVERY control, including the awkward one.

4. Write requirements.md

Use EXACTLY this format (the plan review parses R<n> ids):

# Requirements: <task title>

- **R1** [behavioral] <one atomic, testable requirement>
  - accept: <what a passing test asserts — concrete, observable>
  - source: "<exact clause copied from instruction.md>"
- **R2** [non-behavioral] <e.g. exact response shape / type / annotation>
  - accept: <...>
  - source: "<...>"

Rules:

• [behavioral] = observable runtime behavior; [non-behavioral] = shapes, types, signatures, annotations, naming, exact strings.
• IDs are R1..Rn, contiguous, unique.
• Every sentence/clause of instruction.md must be traceable to at least one R. Nothing dropped.
• accept: must be a CONCRETE, OBSERVABLE check — an exact value, attribute, count, state, type, or string that a test can assert directly (e.g. " equals ", "exactly N of ", "field F has type T and unit U", "attribute A present/absent"). NEVER vague ("works", "is handled", "behaves correctly", "is updated"). A downstream test inherits the strictness of the accept: line: a soft criterion produces a soft test that goes green while a stricter hidden test fails. Pin the tightest exact observable the instruction implies.

5. Self-audit for exhaustiveness (MANDATORY)

• Go clause-by-clause through instruction.md and confirm each maps to an R. List any sentence that does not yet — then add the missing R.
• Re-run the step-3 checklist over the whole instruction one more time. Buried negative / restore / cardinality clauses are the ones that lose tasks.

Output

Submit ONLY one word: done (the work is requirements.md, written via tools — not in the reply).

Rules

• This step produces NO code and NO plan — only requirements.md.
• Exhaustive over clever: more granular atomic requirements is better than fewer broad ones.
• Never invent requirements the instruction does not state; never drop one it does.