| 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
- Read the implementation charter (
docs/host-capability-substrate/implementation-charter.md). Check current version.
- Read the ADR under review.
- Read
DECISIONS.md. Check whether the ADR's decision is already in the Accepted ledger, Pending, or Reversed.
- Read neighboring ADRs in
docs/host-capability-substrate/adr/ for any that depend on or conflict with this one.
- Check the ADR's "Options Considered" section contains at least two real alternatives with explicit pros/cons.
- Check the "Consequences" section lists both accepts and rejects, and notes any future-amendment paths.
- 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.).
- Confirm the ADR's status is appropriate (
proposed, accepted, superseded) and that the date is ISO-8601.
Checks
- Does the decision respect the four-ring architecture?
- Does the decision respect the 15 charter invariants?
- 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:
- Blocking issues (must fix before ADR accepted): missing options, missing consequences, charter invariant conflict, stale charter version citation.
- Non-blocking concerns: clarity, wording, scope ambiguity.
- Suggested follow-ups: additional ADRs the decision implies, regression traps to add, policy updates needed in system-config.
- 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
