to-adr-doc
Skill4 starsChanged 4 months agoApache-2.0View on GitHub
Create and manage Architectural Decision Records as rationale/history records whose accepted software semantics project an exact CCL transaction when applicable.
In this repository51 other files it gives its agents.
- AGENTS.mdAGENTS.md
- architecture-remediationSkill
- attentionSkill
- classify-docSkill
- codebase-designSkill
- codebase-memory-mcpSkill
- codegraphSkill
- coding-standardsSkill
- contract-ledgerSkill
- conventional-commitsSkill
- database-migrationsSkill
- deduplicate-codeSkill
- diagnosing-bugsSkill
- domain-modelingSkill
- format-codeSkill
- github-issue-dependenciesSkill
- graphifySkill
- grillingSkill
- grill-meSkill
- grill-with-docsSkill
- handoffSkill
- implement-ticketSkill
- improve-codebase-architectureSkill
- project-delivery-managementSkill
- project-trackingSkill
- prototypeSkill
- repowiseSkill
- researchSkill
- resolving-merge-conflictsSkill
- review-architectureSkill
- review-specSkill
- setup-matt-pocock-skillsSkill
- spec-contractSkill
- spec-merge-cleanupSkill
- tddSkill
- teachSkill
- to-docSkill
- to-specsSkill
- to-ticketsSkill
- triageSkill
- verify-architectureSkill
- verify-codeSkill
- verify-spec-closureSkill
- verify-specSkill
- verify-ticket-closureSkill
- verify-ticket-decompositionSkill
- wayfinderSkill
- wiki-lintSkill
- wiki-syncSkill
- wiki-synthesizeSkill
- writing-great-skillsSkill
The file
We split this skill into the rules it gives an agent
6 rules. About 0 are common, 4 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈4
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 20
Create an ADR only when all three are true:
- Distinctive: line 30
Use for an accepted material software decision whose semantics are represented by an accepted CCL transaction.
- Distinctive: line 72
Do not add prose inside the generated Decision block.
- Very specific: line 152
Use globally sequential ADR numbers.
- Very specific: line 157
If the Living Entity Wiki exists, invoke $wiki-sync after ADR creation, substantive edit of a proposed ADR, allowed Realization …
- Distinctive: line 165
When an authorized parent already owns an isolated canonical-main authority transaction, consume the exact accepted CCL transaction, …
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
To ADR Doc
$to-adr-doc owns ADR format, numbering, lifecycle, historical immutability, and the
ADR-side projection of accepted Canonical Contract Ledger (CCL) semantics.
ADRs live in docs/adr/.
An ADR explains why a consequential decision was made. When material software semantics are represented by CCL, the ADR does not independently restate or reinterpret what was decided.
Qualification
Create an ADR only when all three are true:
- hard to reverse — later change has meaningful cost;
- surprising without context — future contributors could reasonably ask why;
- real trade-off — meaningful alternatives existed and one was deliberately selected.
Routine implementation choices do not need ADRs.
CCL-backed accepted ADR
Use for an accepted material software decision whose semantics are represented by an accepted CCL transaction.
Required frontmatter:
---
status: accepted
ccl_proposal: sha256:<64-hex>
ccl_transaction: contracts/ccl/transactions/<proposal-hash-without-prefix>.json
---Required body:
# <Short decision title>
## Context
<why this decision was necessary>
## Decision
<exact machine-managed CCL projection>
## Rationale
<why this contract was chosen over material alternatives>## Considered Options and ## Consequences are optional.
Generate the entire ## Decision section only with:
python -m scripts.ccl_adr render-decision <accepted-transaction.json>Then require:
python -m scripts.ccl_adr check-adr <adr-path> <accepted-transaction.json>Do not add prose inside the generated Decision block.
Context/Rationale/Options/Consequences are explanation/history only. They may not introduce material requirements, cardinality, vocabulary, ownership, lifecycle, failure, or other semantics absent from the linked CCL transaction. If explanatory prose reveals a missing semantic requirement, return to the semantic owner.
Historical and non-CCL ADRs
Accepted historical ADRs remain immutable history. Do not rewrite them solely because the current workflow uses CCL.
A genuinely non-semantic architecture record may remain unbacked when no material software contract is created or changed. Do not use that form to bypass CCL for a material semantic decision.
Why Decision is generated
CCL typed assertions = frozen semantic contract
ADR Decision section = deterministic human-readable projection
ADR Context/Rationale = explanation/historyThe generated projection exists for human readability and durable rationale linkage, not as a second machine authority. If it does not match the transaction, the ADR is invalid.
Status lifecycle
Allowed statuses:
proposed
accepted
rejected
deprecated
superseded by ADR-NNNNAllowed transitions:
proposed -> accepted
proposed -> rejected
accepted -> deprecated
accepted -> superseded by ADR-NNNN
deprecated -> superseded by ADR-NNNNrejected and superseded are terminal.
A Wayfinder decision accepted through an exact CCL proposal may create its ADR directly as
accepted in the same authority transaction. A proposed ADR remains legal for exploratory
narrative work, but proposed prose is not accepted CCL authority.
Accepted-content immutability
Once accepted, rejected, deprecated, or superseded, historical decision/rationale content is immutable except narrow Realization Maintenance.
For a CCL-backed ADR, never manually edit ccl_proposal, ccl_transaction, or the
generated ## Decision block. Semantic change requires a new CCL revision and, when
qualified, a successor ADR. Never mutate old history to make it agree with a later
contract.
Reconsideration
- rejected direction becomes viable → create a new ADR explaining what changed;
- accepted decision replaced → create successor CCL/ADR, then mark old ADR superseded;
- accepted decision retired without replacement → mark ADR deprecated; CCL retirement
remains owned by
$contract-ledger.
Realization Maintenance
Permitted maintenance is limited to explanatory realization/reference wording that does
not alter semantic meaning. For CCL-backed ADRs it must never alter CCL frontmatter or the
generated Decision block. Invoke $wiki-sync after allowed maintenance.
Numbering and naming
Use globally sequential ADR numbers. Apply wiki/_schema.md naming rules. Do not invent
entity IDs.
Wiki synchronization
If the Living Entity Wiki exists, invoke $wiki-sync after ADR creation, substantive edit
of a proposed ADR, allowed Realization Maintenance, or status change.
For CCL-backed ADRs pass the linked CCL transaction/contract identities. $wiki-sync
never rewrites CCL or historical ADR semantics to force agreement.
Parent-owned contribution
When an authorized parent already owns an isolated canonical-main authority transaction, consume the exact accepted CCL transaction, create/update only qualified ADR paths, generate/check the Decision projection, invoke required wiki synchronization, and return without committing independently.
Return
For a CCL-backed ADR:
ADR: CREATED | UPDATED | UNCHANGED
Path: <docs/adr/...>
Status: accepted
CCL proposal: <sha256:...>
CCL transaction: <contracts/ccl/transactions/...>
CCL projection check: PASS
Wiki sync: <result | not-applicable>$to-adr-doc does not make semantic decisions, create/revise CCL semantics, choose between
conflicting authorities, write Specs/tickets, or independently determine implementation
realization.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

