skills.rest
thoroc
thorocCOMMUNITY
Explore all skills by this author →
WebsiteGitHub

adr-capture

Extract binding decisions from context files into numbered, immutable Architecture Decision Records.

Updated Apr 9, 2014
Search Tags:#documentation#adr#decision capture#architecture decision record#index generation#supersession#frontmatter validation
One-click install
npx skills add https://github.com/thoroc/thoroc.github.io --skill adr-capture-thoroc
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: adr-capture
Source: https://github.com/thoroc/thoroc.github.io/tree/main/.agents/skills/adr-capture
Command: npx skills add https://github.com/thoroc/thoroc.github.io --skill adr-capture-thoroc

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) and references (resource) and assets (resource) components.

What problem does it solve? Architectural decisions made during planning and analysis often get buried in context files, making them invisible to future contributors and causing repeated re-debate. This Skill captures those binding decisions as numbered, immutable ADRs with a machine-readable index and provenance links back to their source evidence. ## Core Features & Use Cases - Decision Extraction: Identify binding decisions in .context/ plans, findings, and analyses and convert them into numbered ADRs under docs/ADR/ with schema-validated frontmatter. - Index & Coverage Automation: Regenerate docs/ADR/index.yaml and scan context files for decision indicators lacking ADR coverage. - Supersession Workflow: Replace reversed decisions without editing history by marking old ADRs as superseded and linking new ones. - Use Case: After a finding recommends adopting SQLite over PostgreSQL, create an ADR with status: proposed, link the source finding in context:, and regenerate the index so the decision is discoverable. ## Quick Start Ask the agent to extract the decision from a context file and create an ADR, then regenerate the ADR index.

Frequently Asked Questions about adr-capture

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I create an Architecture Decision Record from a context file?▼

Identify the binding decision in the .context/ file, create a new file at docs/ADR/adr-NNN-kebab-case-title.md with frontmatter containing title, status, date, and a context: link to the source file, then run regenerate-adr-index.sh to update the index.

When should I create an ADR versus just recording a finding?▼

Create an ADR only for binding decisions that affect future architecture, conventions, or processes, such as a Recommended Action in a finding. Observational research without a decision should remain a finding, not an ADR.

Can I edit or delete an ADR after it is created?▼

No. ADRs are immutable once created; only the status and superseded_by frontmatter fields may change. To reverse a decision, set the old ADR to status: superseded and create a new ADR with the next number referencing it.

How do I check for decisions that lack ADR coverage?▼

Run scripts/check-undocumented-decisions.sh, which scans .context/ Markdown files for decision indicators like Recommended Action sections and cross-references them against ADR context: links, reporting any undocumented decisions.

Why does ADR frontmatter validation fail on my file?▼

Common causes are a title missing the ADR-NNN: prefix, a status value outside proposed/accepted/deprecated/superseded, or superseded_by present without status: superseded. Run validate-adr-frontmatter.sh to get field-level error details.

Related Skills

Explore More Software Engineering Skills→
Space-DinosaursSpace-Dinosaurs
12

agent-adr-drift-detector

Audit code alignment with documented Architecture Decision Records and generate drift reports.

Official
Advanced
monamaretmonamaret

adr-skill

Create executable Architecture Decision Records with implementation steps and verification criteria.

Community
Advanced
mcj-codermcj-coder
1

documentation-as-code

Lint, spell-check, and validate links in Markdown documentation files.

Community
Intermediate
rghsoftwarerghsoftware

Quick Plan

Generate a single-file markdown plan for small development tasks.

Official
Basic