Create Decisions Document

Create Decisions Document

Repository continuity composition

For repository-scoped work, compose maintain-repository-continuity in Resume mode before selecting work. After an authorized repository change passes domain validation, compose Refresh and Verify immediately before presenting the pull request, and include the reconciled root CONTINUITY.md in the same change. A policy-permitted no-change or exemption result must be documented instead of fabricating an edit.

• Contribute: Decision identifiers, lifecycle state, alternatives, rationale, consequences, and validation
• Never claim: That an automated agent accepted, superseded, or implemented a decision without evidence

Purpose

Create, reconstruct, update, or validate DECISIONS.md and its linked architecture decision records in conformance with architecture-decisions.

The document must answer:

Why is the project the way it is, and which significant accepted choices created the current state?

Use This Skill When

• the canonical decision log is missing
• a significant decision has been accepted
• historical decisions need careful reconstruction
• a decision has been superseded or deprecated
• architecture review needs decision lineage
• implementation or repository structure contains unexplained durable choices
• decision records need validation or migration

Do Not Use This Skill For

• brainstorming
• unaccepted proposals
• meeting summaries
• routine implementation choices
• issue or sprint planning
• fabricated historical rationale

Required Inputs

Resolve:

• governing specification and version
• current architecture documents
• accepted proposal or approval evidence
• contemporaneous issue, pull-request, or discussion history
• implementation and migration evidence
• known alternatives and trade-offs
• decision owner or approving authority
• related and superseding decisions

Missing evidence must remain visible.

Workflow

1. Determine whether the choice is significant enough to record.
2. identify whether the work is a new record, historical reconstruction, correction, outcome update, or supersession.
3. gather contemporaneous evidence.
4. verify that the decision was actually accepted.
5. assign or validate the stable decision identifier.
6. document context, choice, rationale, alternatives, and trade-offs.
7. distinguish evidence, assumptions, uncertainty, and later outcomes.
8. document consequences and review triggers.
9. link affected architecture, proposals, issues, pull requests, and implementation artifacts.
10. validate status and supersession lineage.
11. update the canonical index without creating conflicting duplicates.

Output Contract

Produce:

• DECISIONS.md
• linked ADR files when indexed ADR mode is used
• governing specification identifier and version
• validation results
• evidence gaps and unresolved questions
• affected-artifact review recommendations
• complete supersession lineage

Constraints

• Do not invent rationale, alternatives, or authority.
• Do not rewrite historical reasoning with later knowledge.
• Do not delete superseded decisions.
• Do not promote proposals to accepted decisions without evidence.
• Do not let an index and linked ADR become conflicting canonical copies.
• Do not expose sensitive information unnecessarily.
• Do not claim completion when decision authority or evidence is unresolved.

Validation

Use:

references/validation-checklist.md

and the acceptance criteria in:

architecture-decisions

Completion Criteria

• The decision is significant.
• Acceptance authority is verified.
• Stable identity, status, and date are present.
• Context and rationale reflect contemporaneous evidence.
• Trade-offs and consequences are visible.
• Evidence gaps are explicit.
• Related artifacts are linked.
• Supersession lineage is complete.
• Canonical record ownership is unambiguous.