adr-capture

Stars2

Forks0

UpdatedJuly 7, 2026 at 18:43

Capture Architecture Decision Records (ADRs) from .context/ plans, findings, and analyses. Extracts binding decisions into numbered ADRs under docs/ADR/, maintains a machine-readable index, and validates coverage. Use when creating or reviewing context files that contain decisions. DO NOT use for observational findings without decisions, retroactive documentation of long-settled decisions, or inline comments. Triggers: 'capture decision', 'create ADR', 'document decision', 'architectural decision', 'record decision as ADR', 'extract decisions', 'ADR review', 'index ADRs', 'check ADR coverage'.

Installation

Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.

Source

pantheon-org

pantheon-org/skill-quality-auditor

View GitHub Repository View Creator Repositories

Download

Related occupationsSOC

Based on SOC occupation classification

Software DevelopersComputer and Mathematical Occupations·SOC 15-1252

File Explorer

28 files

SKILL.md

readonly

More from this repository

same repository

skill-quality-auditor

pantheon-org/skill-quality-auditor

Evaluate, score, and remediate agent skill collections using a 9-dimension quality framework (Knowledge Delta, Mindset, Anti-Patterns, Specification Compliance, Progressive Disclosure, Freedom Calibration, Pattern Recognition, Practical Usability, Eval Validation). Performs duplication detection, generates remediation plans with T-shirt sizing, enforces CI quality gates, validates artifact conventions, tracks score trends, and provides a native eval runner with LLM-as-judge (BYOK, provider-agnostic). Use when evaluating skill quality, auditing SKILL.md files, scoring agent skills, generating remediation plans, detecting duplicate skills, validating skill format, enforcing quality gates, optimizing for A-grade publication, comparing audit baselines, batch skill assessments, or checking skill registry compliance. Triggers: 'check my skills', 'skill audit', 'improve my SKILL.md', 'quality check', 'A-grade scoring', 'quality gates', 'eval validation', 'audit all skills', 'remediation plan', 'skill judge', 'dimens

2026-07-142

context-file

pantheon-org/skill-quality-auditor

Create a new .context/ file (plan, finding, or analysis) with standard YAML frontmatter. Use when documenting a decision, writing an implementation plan, recording research findings, or capturing analysis output. DO NOT use for ephemeral notes, secrets storage, or skill remediation plans (use skill-auditor remediate instead). Triggers: 'create a plan', 'new finding', 'document this', 'write analysis', 'new context file', 'capture findings', 'draft a plan', 'record decision'.

2026-07-072

context-index

pantheon-org/skill-quality-auditor

Regenerate .context/index.yaml from all .context/**/*.md frontmatter, and validate all files carry standard YAML frontmatter. Use when the index is stale, files were added or removed, or the pre-commit hook blocks on missing frontmatter. DO NOT use to create new context files (use context-file skill instead), to edit index.yaml by hand, or as a substitute for fixing frontmatter issues at the source. Triggers: 'update context index', 'regenerate index', 'context index stale', 'sync context', 'what context files exist', 'frontmatter missing', 'index .context'.

2026-07-072

plan-review

pantheon-org/skill-quality-auditor

Review .context/plans/*.md files using 3 independent subagent reviewers: Technical (feasibility, gaps, soundness), Strategic (scope, alignment, priority), and Risk (blind spots, edge cases, failure modes). The skill FIRST asks the user which models to assign to each reviewer — presenting available options based on the user's environment (OpenCode Zen, Go, Claude Code, or BYOK). Each reviewer receives the same plan with a role-specific lens and returns structured feedback. The main agent consolidates all three perspectives. Triggers: 'review this plan', 'audit plan', 'plan review', 'check my plan', 'what's wrong with this plan', 'review all plans', 'plan quality check'. Do NOT use for plans not in .context/plans/, one-off notes, or external documents.

2026-07-072

external-source-fit

pantheon-org/skill-quality-auditor

Assess whether an external GitHub repo, file, project fits the skill-quality-auditor project: what it actually is (not what its name implies); whether it overlaps existing capability (D1-D9 scorers, validate, duplication, eval runner, helper skills); whether it belongs in the Go CLI versus a helper skill; what is worth learning from even a rejected source; whether the project needs it. Ends by writing a house-standard FINDING, flagging any binding decision for ADR capture. Use when someone links an external repo, file, project asking whether it fits, whether we can learn from it, whether we need it. Do NOT use for reviewing internal code (use review-changes), scoring a SKILL.md (use skill-quality-auditor), doing web research (use deep-research). Triggers: 'does this repo fit', 'evaluate this project', 'assess this external repo', 'would this fit our project', 'can we learn from', 'is this worth adopting', 'fit assessment', 'should we import', 'should we port this'.

2026-07-072

plan-create

pantheon-org/skill-quality-auditor

Create .context/plans/*.md files with standard YAML frontmatter, phases/tasks/waves decomposition, and post-creation validation. Infers section conventions from existing plans in .context/plans/ to match the local style. Integrates with plan-review for a create → review → iterate loop. Triggers: 'create a plan', 'new plan', 'draft a plan', 'plan scaffold', 'write a plan'. Do NOT use for plans outside .context/plans/, ephemeral notes, or the main project SKILL.md.

2026-07-062

name

adr-capture

description

ADR Capture

Capture Architecture Decision Records from .context/ analysis, findings, plans, and reviews. Automatically extract decisions, create numbered ADRs, and maintain the index.

Immutability rule: Immutability begins at acceptance, not creation. A proposed, unmerged ADR is a draft and may be edited freely in place. Once accepted, an ADR's title, body, and context fields are frozen and only status and superseded_by may change; to replace an accepted decision, supersede it — create a new ADR and mark the old one as superseded. See ADR-061.

Prerequisites

A .context/ file (plan, finding, or analysis) containing a binding decision — a choice that affects future development direction, architecture, conventions, or processes
The context-file skill to create the source .context/ file if it doesn't exist yet
assets/schemas/adr-frontmatter.schema.json and assets/templates/adr-template.yaml for schema validation

Quick Start

# Regenerate ADR index after adding or updating ADRs
scripts/regenerate-adr-index.sh

# Check for decisions in context files that lack ADRs
scripts/check-undocumented-decisions.sh

ADR Location and Structure

ADRs live at docs/ADR/adr-NNN-kebab-case-title.md. See docs/ADR/index.yaml for the full list.

ADR Frontmatter Schema

Every ADR MUST start with frontmatter. Use the template at assets/templates/adr-template.yaml to bootstrap new files.

---
title: "ADR-NNN: Human-readable decision title"
status: proposed | accepted | deprecated | superseded
date: YYYY-MM-DD
superseded_by: "adr-NNN"     # only when status is "superseded"
context:
  - path: .context/findings/topic-YYYY-MM-DD.md
---

Field rules:

title — Must start with ADR-NNN: prefix; wrap in quotes
status — proposed until reviewed, accepted for active decisions, deprecated or SUPERSEDED when replaced
date — Creation date in ISO format; do not update on edits
superseded_by — Only when status: superseded; value is the replacement ADR name
context — List of relative paths to .context/ files that motivated the decision; omit entirely if none

ADR Body Template

**Status:** Proposed
**Date:** YYYY-MM-DD

## Context

What is the issue motivating this decision or change?

## Decision

What is the change being proposed or implemented?

## Consequences

What becomes easier or more difficult because of this change?

When to Use

Create an ADR whenever a .context/ file or a review makes a binding decision — a choice that affects future direction, architecture, conventions, or processes. ALWAYS link the ADR to its source context file.

Context file section	Decision example	ADR warranted?
Finding > Recommended Action	"Adopt Option A (native Go eval runner)"	Yes
Plan > Steps	"Phase 1: split reporter into sub-packages"	Yes
Plan > Open Questions	"Use sqllite vs postgres" — after resolved	Yes
Finding > Summary	"Observational research with no action"	No

When NOT to Use

Observational findings without decisions — record as findings, not ADRs
Retroactive documentation of long-settled decisions — ADRs capture forward-looking choices
Inline comments or ephemeral notes — not every observation needs a decision record

Workflow

When creating a context file that contains a decision, create the ADR in the same session
Use the template — link the context file in the context: frontmatter field
Run the index regeneration script after creating the ADR
Set status: proposed initially; promote to accepted after implementation starts
When a decision is superseded: set status: superseded and superseded_by on the old ADR; create a new ADR referencing the old one via context:
After a PR merges, run scripts/merge-status-sync.sh --dry-run <pr-number> to check whether the PR closes out any linked plan or ADR that's still ACTIVE/DRAFT/proposed. Single-phase plans directly or frontmatter-linked to the PR auto-flip to DONE via a branch + PR when run without --dry-run; multi-phase plans, ADRs, and file-touch-only links are always flagged for a human to confirm — see references/merge-status-sync.md.

Scripts

scripts/validate-adr-frontmatter.sh        # Validate ADR frontmatter against JSON schema
scripts/regenerate-adr-index.sh            # Scan docs/ADR/ and regenerate index.yaml
scripts/check-undocumented-decisions.sh    # Find decisions without ADR coverage
scripts/merge-status-sync.sh               # Detect and (optionally) apply post-merge plan/ADR status drift

Mindset

Not every finding needs an ADR — only decisions that shape future work
The context: frontmatter field links decisions to their evidence; always populate it
status: proposed is the safe default; promote after implementation review
ADRs are immutable once accepted — a proposed/unmerged ADR may still be edited in place; after acceptance only status and superseded_by may be updated, and superseding is the only way to replace the decision
Consider marking status: superseded rather than deleting old ADRs; the historical record preserves context even for reversed decisions
Use production-grade terminology: pitfall, gotcha, ALWAYS, NEVER, anti-pattern

Troubleshooting

Problem                                 | Solution
Index not updating after ADR creation   | Run scripts/regenerate-adr-index.sh
Pre-commit hook blocking                | Run scripts/validate-adr-frontmatter.sh
Decision not found in ADR index         | Check the ADR has context: and valid frontmatter

Anti-Patterns

NEVER create an ADR without linking the source context file. WHY: The context: field is the provenance chain — without it the decision is untethered from its evidence. BAD: Creating an ADR with no context: references for a decision from a review. GOOD: Always include context: with the relative path to the .context/ file.

NEVER edit or delete an accepted ADR (a proposed/unmerged one may still be refined in place). WHY: Accepted ADRs are immutable records. Editing an accepted ADR distorts history; deleting erases the rationale trail. BAD: Rewording the body of an accepted ADR to reflect new understanding. GOOD: Set status: superseded and superseded_by; create a new ADR.

NEVER reuse ADR numbers. WHY: ADR numbers are permanent identifiers — reusing a number erases the mapping. GOOD: Always increment to the next unused number.

NEVER skip creating an ADR when a .context/ file contains a clear decision. WHY: The decision will be invisible to agents reading the ADR index, causing re-debate. GOOD: Create both the plan and ADR in the same session.

References

Topic	Reference	When to Use
ADR frontmatter field rules, status lifecycle, and validation	ADR Frontmatter Schema	Validating or debugging ADR frontmatter errors
Step-by-step supersession workflow with examples	ADR Supersession	Reversing or replacing an existing decision via supersession
Post-merge plan/ADR status drift detection: signals, auto-flip rules, usage	Merge Status Sync	Checking or applying status drift after a PR merges