decided-review

name	decided-review
description	Review and triage a RAC (requirements-as-code) corpus using the decided CLI — work prioritised findings worst-first until validation and relationship checks pass. Use when asked to review, triage, or fix findings across a project's AsDecided corpus (the decisions/ directory).

AsDecided corpus review

decided review <dir> validates every artifact, checks every relationship, and reports findings grouped by priority, worst first. This skill is the procedure for working that report down: blocking findings first, then advisory ones, re-validating after each fix.

Hard constraints

• Write artifact files only inside the host project's decisions directory (decisions/ by default; if the project keeps artifacts elsewhere, confirm the path before writing). Never create or edit RAC artifacts outside that directory, and never modify files elsewhere in the project on this skill's behalf.
• Never hand-write or alter an artifact id or its frontmatter identity block. Do not edit .decisions/config.yaml.
• Do not invent sections or frontmatter fields. Use decided schema <type> to see what a type expects.
• The work is done only when decided validate <dir> and decided relationships <dir> --validate both exit 0.

Run the review

decided review <dir>            # findings grouped by priority, worst first
decided review <dir> --json     # stable contract for scripted triage

Exit 1 means blocking findings exist; exit 0 with findings means only advisory items remain. Findings are grouped by priority:

1. Invalid artifacts — validation errors (blocking)
2. Broken relationships — unresolvable references (blocking)
3. Unrecognized artifacts — no schema matched (advisory)
4. Missing recommended information (advisory)

Work strictly in priority order. Each finding carries a suggested action; start from it.

Mechanical findings — missing sections

Missing recommended sections are mechanical: the fix is adding the section with real content.

decided improve <file>             # missing sections, with guidance prompts
decided improve <file> --template  # Markdown stubs for the missing sections

Paste the stub, then replace its placeholder text with real content. Do not add a section purely to silence a finding — when no real content exists, an advisory finding may stand.

Judgement findings — broken or ambiguous references

A reference under a ## Related ... section that points at nothing, at more than one artifact, or at a duplicated identifier needs investigation, not a template. Check what the reference actually resolves to:

decided resolve <id> <dir>    # resolved, not found, or duplicate
decided find <text> <dir>     # locate the artifact the reference meant

• Not found: the target was renamed, moved, or never existed. Find the intended artifact with decided find and correct the reference to an identifier that resolves.
• Ambiguous or duplicate identifier: more than one artifact answers to the same identifier. Fix the duplicated identity — typically a repeated ## ID value or two files sharing an aliased filename — never by editing a frontmatter id.
• Self-reference: an artifact lists itself; remove the entry.

Re-validate after each fix

decided validate <dir>
decided relationships <dir> --validate

Run both after every fix, not once at the end — a fix can introduce a new finding. Finish by re-running decided review <dir> to confirm the blocking findings are gone.

Output for automation

Most commands accept --json for machine-readable output, and exit codes follow the documented contract (0 pass, non-zero failure). Prefer --json when a result feeds a script or a decision.