hcs-adr-review

name: hcs-adr-review description: Review an Architecture Decision Record (ADR) in this repo for boundary discipline, charter compliance, and decision-ledger consistency. allowed-tools: Read, Grep, Glob

Skill: Review an ADR

Use when a PR adds or amends a file under docs/host-capability-substrate/adr/, or when a human asks "review ADR N".

Inputs

• Path to the ADR being reviewed (e.g., docs/host-capability-substrate/adr/0005-process-model-launchd.md)
• The PR branch or commit range containing the change

Procedure

1. Read the implementation charter (docs/host-capability-substrate/implementation-charter.md). Check current version.
2. Read the ADR under review.
3. Read DECISIONS.md. Check whether the ADR's decision is already in the Accepted ledger, Pending, or Reversed.
4. Read neighboring ADRs in docs/host-capability-substrate/adr/ for any that depend on or conflict with this one.
5. Check the ADR's "Options Considered" section contains at least two real alternatives with explicit pros/cons.
6. Check the "Consequences" section lists both accepts and rejects, and notes any future-amendment paths.
7. Check the "References" section cites at least the charter, the research plan, and any applicable external docs (MCP spec, Claude Code docs, Codex docs, etc.).
8. Confirm the ADR's status is appropriate (proposed, accepted, superseded) and that the date is ISO-8601.
9. Smoke-test citations: re-verify every cited path:line against the file state under review before returning a verdict — do not carry file/line claims from an earlier read or recollection.

Checks

• Does the decision respect the four-ring architecture?
• Does the decision respect the charter's non-negotiable invariants (the full numbered set in the current charter — do not assume a count)?
• Does the decision stay inside the substrate's owns list (not domain-server territory)?
• Is the decision narrow enough to be implementable in one PR, or does it imply multiple PRs?
• Does the ADR cite the charter version it was written against?
• If the ADR changes a previously-accepted decision, is there a corresponding entry in DECISIONS.md Reversed?

Output format

Return:

1. Blocking issues (must fix before ADR accepted): missing options, missing consequences, charter invariant conflict, stale charter version citation.
2. Non-blocking concerns: clarity, wording, scope ambiguity.
3. Suggested follow-ups: additional ADRs the decision implies, regression traps to add, policy updates needed in system-config.
4. Charter compliance statement: explicit confirmation.

Escalation

If the ADR involves schema/ontology, request hcs-ontology-reviewer. If it involves policy, request hcs-policy-reviewer. If it involves security-sensitive changes, request hcs-security-reviewer.

Reference

• Charter: docs/host-capability-substrate/implementation-charter.md
• Decision ledger: DECISIONS.md
• ADR template: docs/host-capability-substrate/adr/0000-template.md