Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
66 changes: 33 additions & 33 deletions .agents/skills/adr-linter/SKILL.md
Original file line number Diff line number Diff line change
@@ -1,33 +1,33 @@
---
name: adr-linter
description: Review an ExStruct ADR draft for required sections, status values, evidence quality, supersede links, and balanced consequences. Use when an ADR already exists in draft form and you need findings before review or merge.
---

# ADR Linter

Review the ADR as a decision record, not as prose polish.

## Read

1. `dev-docs/agents/adr-governance.md`
2. `dev-docs/agents/adr-workflow.md`
3. `dev-docs/adr/template.md`
4. Related ADRs if the draft mentions supersede or overlap

## Workflow

1. Validate the status value.
2. Check that the ADR has `状態`, `背景`, `決定`, `影響`, `根拠`, `Supersedes`, and `Superseded by`.
3. Verify that `根拠` contains concrete `Tests`, `Code`, or `Related specs`.
4. Check that consequences include tradeoffs, not only benefits.
5. If supersede or replacement is claimed, verify the referenced ADR links are present and consistent.

## Output Contract

Return findings first, ordered by severity.

- `high`: contract hole, missing decision, invalid status, missing supersede linkage
- `medium`: weak context, weak evidence, one-sided consequences
- `low`: clarity or consistency issues

If no findings exist, say that explicitly and mention any residual review risk.
---
name: adr-linter
description: Review an ExStruct ADR draft for required sections, status values, evidence quality, supersede links, and balanced consequences. Use when an ADR already exists in draft form and you need findings before review or merge.
---
# ADR Linter
Review the ADR as a decision record, not as prose polish.
## Read
1. `dev-docs/agents/adr-governance.md`
2. `dev-docs/agents/adr-workflow.md`
3. `dev-docs/adr/template.md`
4. Related ADRs if the draft mentions supersede or overlap
## Workflow
1. Validate the status value.
2. Check that the ADR has `状態`, `背景`, `決定`, `影響`, `根拠`, `Supersedes`, and `Superseded by`.
3. Verify that `根拠` contains concrete `Tests`, `Code`, or `Related specs`.
4. Check that consequences include tradeoffs, not only benefits.
5. If supersede or replacement is claimed, verify the referenced ADR links are present and consistent.
## Output Contract
Return findings first, ordered by severity.
- `high`: contract hole, missing decision, invalid status, missing supersede linkage
- `medium`: weak context, weak evidence, one-sided consequences
- `low`: clarity or consistency issues
If no findings exist, say that explicitly and mention any residual review risk.
138 changes: 69 additions & 69 deletions .agents/skills/adr-reviewer/SKILL.md
Original file line number Diff line number Diff line change
@@ -1,69 +1,69 @@
---
name: adr-reviewer
description: Review an ExStruct ADR draft for decision quality, overlap with existing ADRs and specs, evidence strength, rollout risk, and human-ownership escalations. Use only after adr-linter reports no unresolved high/medium findings on the current draft, and when you need design-review findings before merge or handoff.
---

# ADR Reviewer

Review the policy decision, not just the document shape.

## Read

1. `dev-docs/agents/adr-governance.md`
2. `dev-docs/agents/adr-criteria.md`
3. `dev-docs/agents/adr-workflow.md`
4. `dev-docs/specs/adr-review.md`
5. The target ADR draft
6. Related ADRs, relevant public docs under `docs/` when public API / CLI / MCP contracts are in scope, internal specs, tests, src paths, and issue / PR context
7. Existing `adr-linter` findings for the current draft

## Workflow

1. Confirm the current draft has no unresolved `adr-linter` `high` / `medium` findings. Only proceed with design review after that precondition is met.
2. Read the ADR draft and identify the single policy question it is trying to resolve.
3. Check whether the draft overlaps with, contradicts, or should supersede an existing ADR or spec.
4. Verify that the cited `Tests`, `Code`, and `Related specs` actually support the claims being made, and include relevant public `docs/` pages in scope when the ADR touches public API / CLI / MCP contracts.
5. Review whether compatibility, rollout, fallback, migration, or safety consequences are covered when relevant.
6. Detect human-owned decisions that AI should not settle, including public API break judgment, security or license calls, major directory reorganization, or unresolved product/spec direction.
7. Return one verdict:
- `ready`
- `revise`
- `escalate`

## Output Contract

Return findings first, ordered by severity, and include:

- `verdict`
- `scope`
- `draft`
- `related ADRs`
- `public docs`
- `specs`
- `src`
- `tests`
- `issue / PR context`
- `findings`

Each finding should include:

- `type`
- `decision-gap`
- `scope-conflict`
- `evidence-risk`
- `rollout-gap`
- `ownership-escalation`
- `severity`
- `summary`
- `why it matters`
- `suggested revision`
- `evidence`
- `draft`
- `related sources`

Also include top-level:

- `open questions`
- `residual risks`

Do not silently rewrite the ADR text. If the review hits a human-owned decision, return `escalate` instead of inventing a final policy.
---
name: adr-reviewer
description: Review an ExStruct ADR draft for decision quality, overlap with existing ADRs and specs, evidence strength, rollout risk, and human-ownership escalations. Use only after adr-linter reports no unresolved high/medium findings on the current draft, and when you need design-review findings before merge or handoff.
---
# ADR Reviewer
Review the policy decision, not just the document shape.
## Read
1. `dev-docs/agents/adr-governance.md`
2. `dev-docs/agents/adr-criteria.md`
3. `dev-docs/agents/adr-workflow.md`
4. `dev-docs/specs/adr-review.md`
5. The target ADR draft
6. Related ADRs, relevant public docs under `docs/` when public API / CLI / MCP contracts are in scope, internal specs, tests, src paths, and issue / PR context
7. Existing `adr-linter` findings for the current draft
## Workflow
1. Confirm the current draft has no unresolved `adr-linter` `high` / `medium` findings. Only proceed with design review after that precondition is met.
2. Read the ADR draft and identify the single policy question it is trying to resolve.
3. Check whether the draft overlaps with, contradicts, or should supersede an existing ADR or spec.
4. Verify that the cited `Tests`, `Code`, and `Related specs` actually support the claims being made, and include relevant public `docs/` pages in scope when the ADR touches public API / CLI / MCP contracts.
5. Review whether compatibility, rollout, fallback, migration, or safety consequences are covered when relevant.
6. Detect human-owned decisions that AI should not settle, including public API break judgment, security or license calls, major directory reorganization, or unresolved product/spec direction.
7. Return one verdict:
- `ready`
- `revise`
- `escalate`
## Output Contract
Return findings first, ordered by severity, and include:
- `verdict`
- `scope`
- `draft`
- `related ADRs`
- `public docs`
- `specs`
- `src`
- `tests`
- `issue / PR context`
- `findings`
Each finding should include:
- `type`
- `decision-gap`
- `scope-conflict`
- `evidence-risk`
- `rollout-gap`
- `ownership-escalation`
- `severity`
- `summary`
- `why it matters`
- `suggested revision`
- `evidence`
- `draft`
- `related sources`
Also include top-level:
- `open questions`
- `residual risks`
Do not silently rewrite the ADR text. If the review hits a human-owned decision, return `escalate` instead of inventing a final policy.
Loading
Loading