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
1---2name: hcs-adr-review3description: Review an Architecture Decision Record (ADR) in this repo for boundary discipline, charter compliance, and decision-ledger consistency.4---5
6# Skill: Review an ADR
7
8Use when a PR adds or amends a file under `docs/host-capability-substrate/adr/`, or when a human asks "review ADR N".
9
10## Inputs
11
12- Path to the ADR being reviewed (e.g., `docs/host-capability-substrate/adr/0005-process-model-launchd.md`)
13- The PR branch or commit range containing the change
14
15## Procedure
16
171. Read the implementation charter (`docs/host-capability-substrate/implementation-charter.md`). Check current version.
182. Read the ADR under review.
193. Read `DECISIONS.md`. Check whether the ADR's decision is already in the Accepted ledger, Pending, or Reversed.
204. Read neighboring ADRs in `docs/host-capability-substrate/adr/` for any that depend on or conflict with this one.
215. Check the ADR's "Options Considered" section contains at least two real alternatives with explicit pros/cons.
226. Check the "Consequences" section lists both accepts and rejects, and notes any future-amendment paths.
237. 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.).
248. Confirm the ADR's status is appropriate (`proposed`, `accepted`, `superseded`) and that the date is ISO-8601.
25
26## Checks
27
28- Does the decision respect the four-ring architecture?
29- Does the decision respect the 15 charter invariants?
30- Does the decision stay inside the substrate's owns list (not domain-server territory)?
31- Is the decision narrow enough to be implementable in one PR, or does it imply multiple PRs?
32- Does the ADR cite the charter version it was written against?
33- If the ADR changes a previously-accepted decision, is there a corresponding entry in `DECISIONS.md` Reversed?
34
35## Output format
36
37Return:
38
391. **Blocking issues** (must fix before ADR accepted): missing options, missing consequences, charter invariant conflict, stale charter version citation.
402. **Non-blocking concerns**: clarity, wording, scope ambiguity.
413. **Suggested follow-ups**: additional ADRs the decision implies, regression traps to add, policy updates needed in system-config.
424. **Charter compliance statement**: explicit confirmation.
43
44## Escalation
45
46If the ADR involves schema/ontology, request `hcs-ontology-reviewer`.
47If it involves policy, request `hcs-policy-reviewer`.
48If it involves security-sensitive changes, request `hcs-security-reviewer`.
49
50## Reference
51
52- Charter: `docs/host-capability-substrate/implementation-charter.md`
53- Decision ledger: `DECISIONS.md`
54- ADR template: `docs/host-capability-substrate/adr/0000-template.md`
aibot88