requirement-status

name

requirement-status

description

Use when surveying or updating the implementation status of `requirements/RNN-*.md` against the current `source/` and `reports/`. The status model is multi-axis (not binary done/not-done) because parts can exist as building blocks for a larger exploration even when no single requirement is "done", and shipped features may differ from the requirement on purpose. Trigger on "update requirement status", "requirement status", "show the status table", "what's the status of R0N", "update the tracker".

Requirement status — survey and update the contract tracker

requirements/RNN-*.md declares the final contract (forward-looking). This skill is for populating and updating the status sections of those files, plus the index table in requirements/README.md, against the current source/ and reports/.

The product is built by maximum-feature exploration first, then split and promote. So the gap between a requirement and the source tree is not binary; multiple axes apply at once.

Axes (orthogonal, all apply at once)

Track each requirement on all four axes, not on a single status word.

1. Coverage — how much of the requirement's acceptance criteria is satisfied by something currently in source/.
   • none / partial / full / exceeds (more is shipped than required).
2. Form — how the existing code relates to the requirement shape.
   • aligned — shipped shape matches the requirement.
   • parts — building blocks exist, but not yet arranged as the requirement describes (parts-as-blocks, awaiting split/recombine).
   • superset — a larger feature contains the requirement as a subset (max-feature-first; awaiting promotion of the relevant slice).
   • divergent — what is shipped intentionally differs from the requirement (record the reason, do not auto-flag as broken).
3. Stability — how settled the existing implementation is.
   • experimental (PoC, may be reshaped) / stabilizing / shipped (in docs/).
4. Drift — does the requirement file itself still match reality / current intent?
   • current / stale (requirement text needs to catch up).

A requirement that is "65% covered by parts that live inside a larger exploration" is a normal state, not a failure. Record it as coverage=partial / form=parts+superset / stability=experimental / drift=current — that is information, not a bug.

The legacy single-word status field in the requirements/README.md index stays for at-a-glance scanning, derived from the axes:

• unknown — the four axes have not been filled in yet.
• not-started — coverage=none and no relevant parts/superset.
• partial — anything in between.
• shipped — coverage>=full AND stability=shipped AND drift=current.
• divergent — form=divergent, intentional. Surface in the index so it is not silently lost.

File schema (extend, do not replace)

requirements/RNN-*.md already has section ## 5. Status. Extend it to:

## 5. Status

| Axis      | Value                            | Notes |
| --------- | -------------------------------- | ----- |
| coverage  | none/partial/full/exceeds        | <how much of the requirement is satisfied> |
| form      | aligned/parts/superset/divergent | <how it exists as building blocks> |
| stability | experimental/stabilizing/shipped | <degree of shipping> |
| drift     | current/stale                    | <freshness of the requirement text> |

- Related source owner: <path…> (if it rides on a larger feature, also name the parent feature)
- Related reports: <reports/...> (the exploration history)
- Related docs: <docs/...> (already promoted)
- Whereabouts as parts: <each acceptance criterion of the requirement → which building block carries it>
- Intentional divergence: <only when form=divergent. why it is allowed to diverge>
- Next: <expected action such as promote / split / requirement revision. may be empty>

The index table in requirements/README.md lists the single derived status word together with the form as supplementary info:

| ID  | Title | Category | Status (coverage/form/stability) |

Survey procedure (read-only pass)

When asked "update the status" or "show the tracker":

1. List requirements: read the index in requirements/README.md and all corresponding RNN-*.md files.
2. For each requirement, build the axis values by:
   • Searching source/ with grep / find for the acceptance-criteria keywords (role words, screen names, endpoint names, domain words). Use the Explore subagent for breadth when there are many requirements; the orientation tool (indexion agent orient over source reports) is the heavier hammer for unfamiliar areas.
   • Searching reports/ by directory name for related PoCs. Assume one requirement may span multiple reports / reports are not 1:1 with requirements (consistent with the build the maximum feature, then split practice).
   • Searching docs/ for whether a shipped entry exists.
3. Decide axis values per requirement, with these rules:
   • Exists as parts, but not yet assembled as the requirement-level screen/contract → form=parts; evaluate coverage only for the acceptance criteria that are met.
   • The requirement is buried as a subset inside one larger feature → form=superset; write the parent feature name in the notes column (a later target for "promote = carve out").
   • Spec and implementation differ but intentionally → form=divergent; always write the reason (no action required — it becomes material to settle later).
   • The requirement-side wording is stale / the implementation has become the correct answer → drift=stale. In this case, either rewrite the requirement body or append to the "change history".
4. Do not silently downgrade: do not write a parts-as-blocks state as not-started. Keeping the form=parts fact on record is the information that a later optimization (split → promote) needs.

Update procedure (write pass)

When the survey result is approved:

1. Fill each requirements/RNN-*.md ## 5. Status table with the schema above. For a blank cell, enter the most recently determined value rather than unknown (mark only a genuinely unknown axis as unknown).
2. Append one line to ## 6. Change history: YYYY-MM-DD: status updated (coverage=…, form=…).
3. Update the index table in requirements/README.md with the derived single status word plus the form supplement.
4. If the requirement text needs revising (drift=stale), do not fold it into the status update: keep the requirement's ## 1. Original requirement intact and append the current interpretation under ## 2. Axes or a separate section. Never rewrite the original text (it would erase the trail of contract revisions).

Anti-patterns (avoid these)

• Binary compression: collapsing to done / not-done. The meaning of the multiple axes is lost.
• Wanting to bind requirements and reports 1:1: reports are per purpose; one requirement may span multiple reports, and vice versa. Write related reports as a set.
• Rushing to promote a superset: "build the maximum feature, then split into the optimal unit" is the policy. form=superset is a normal state, not an instruction to carve it out immediately.
• Treating divergent as a defect: an intentional divergence is something to record, not something to fix. Whether to fix it is a separate decision.
• Letting a status update silently expand into source edits: this skill is limited to updating requirements/ and requirements/README.md. If an implementation change is needed, split it out into the normal fix-as-poc / isolate-and-integrate flow.

Output (when invoked to "show" without writing)

When the user asks to "show the status table", do not rewrite any file — return the single table below in the conversation (if it diverges from the latest values in the files, confirm: "shall I update the files too?"):

| ID  | Title | coverage | form  | stability    | drift   | Whereabouts of parts / parent feature |
| --- | ----- | -------- | ----- | ------------ | ------- | ------------------------------------- |
| R01 | …     | partial  | parts | experimental | current | …                                     |

Always confirm with the user before writing. A survey is always safe, but an update is a candidate commit to requirements/, so never do it unprompted.