git-adr Skill

Comprehensive skill for managing Architecture Decision Records using the git-adr CLI tool.

Auto-Context Loading

At session start, if in a git-adr repository, automatically load ADR summary:

# Silent detection and load
git notes --ref=adr list &>/dev/null && git adr list --format oneline 2>/dev/null

This provides awareness of existing decisions without consuming excessive context. See workflows/session-start.md for full behavior.

On-Demand Hydration

Use progressive loading for token efficiency:

| Trigger | Action | |---------|--------| | "Show me ADR {id}" | git adr show {id} → full content | | "What did we decide about X" | git adr search "X" → snippets | | "Record this decision" | Guided creation workflow |

See workflows/decision-recall.md for recall patterns. See workflows/decision-capture.md for creation flow.

CRITICAL RULES

NEVER modify user configuration without explicit permission.

Do NOT run git-adr config --set or git config adr.* commands unless the user explicitly asks to change config
Do NOT "check" config by running set commands - use git config --get or git-adr config --get only
Before using AI features, READ the existing config with git config --local --list | grep adr - do NOT assume or set values
If AI config is missing, ASK the user what provider/model they want - do NOT set defaults
The user's config is sacred - treat it as read-only unless explicitly told otherwise

What is git-adr?

git-adr is a command-line tool that manages ADRs using git notes instead of files:

Non-intrusive: ADRs don't clutter the working tree
Portable: Travel with git history
Linkable: Associate decisions with commits
Syncable: Push/pull like regular git content

Quick Command Reference

| Command | Description | |---------|-------------| | git adr init | Initialize ADR tracking | | git adr new "<title>" | Create new ADR | | git adr list | List all ADRs | | git adr show <id> | Display an ADR | | git adr edit <id> | Edit an ADR | | git adr search "<query>" | Search ADRs | | git adr supersede <old-id> "<title>" | Supersede a decision | | git adr link <id> <commit> | Link ADR to commit | | git adr sync --push | Push ADRs to remote | | git adr sync --pull | Pull ADRs from remote | | git adr stats | Show statistics | | git adr export | Export to files | | git adr config list | Show configuration |

For full command documentation, see references/commands.md.

Execution Patterns

Before Executing Commands

Always verify the environment:

# 1. Check git-adr is installed
git adr --version

# 2. Verify in a git repository
git rev-parse --is-inside-work-tree

# 3. For most commands, check if initialized
git notes --ref=adr list 2>/dev/null || echo "Not initialized"

Error Handling

If git-adr is not installed:

git-adr is not installed. Install with:
  cargo install git-adr
  # or
  brew tap zircote/tap && brew install git-adr

If not in a git repository:

git-adr requires a git repository. Initialize with:
  git init
  git adr init

If ADRs not initialized:

ADR tracking not initialized. Run:
  git adr init

Format Selection

Reading Project Configuration

Always check the project's configured template before generating content:

# Get configured template (defaults to madr if not set)
TEMPLATE=$(git config --get adr.template 2>/dev/null || echo "madr")
echo "Using template: $TEMPLATE"

Available Formats

| Format | Config Value | Best For | |--------|--------------|----------| | MADR | madr | General purpose, option analysis (default) | | Nygard | nygard | Quick, minimal decisions | | Y-Statement | y-statement | Ultra-concise, single sentence | | Alexandrian | alexandrian | Pattern-based, forces analysis | | Business Case | business | Stakeholder approval, ROI | | Planguage | planguage | Measurable quality requirements |

For format templates, see references/formats/.

Creating ADRs

Workflow

Check format: Read adr.template config
Load template: Read appropriate format from references/formats/
Generate content: Fill template with user's context
Execute command: git adr new "<title>" with content

Example: Creating a MADR

# Create ADR (opens editor with template)
git adr new "Use PostgreSQL for primary database"

# Or with specific format override
git adr new "Use PostgreSQL" --template nygard

When generating content, follow the structure in the appropriate format template.

Common Workflows

New Project Setup

git adr init
git adr new "Record architecture decisions"
git adr sync --push

Team Collaboration

git adr sync --pull        # Get latest
git adr new "Add caching"  # Create decision
git adr sync --push        # Share with team

Linking to Implementation

# After implementing a decision
git adr link 20250115-use-postgresql abc1234

# View linked commits
git adr show 20250115-use-postgresql

Superseding Decisions

# When replacing a decision
git adr supersede 20250101-use-mysql "Migrate to PostgreSQL"

For more workflows, see references/workflows.md.

Configuration

Common configuration options:

# Set default template
git adr config adr.template madr

# Set editor
git adr config --global adr.editor "code --wait"

# Enable auto-sync
git adr config adr.sync.auto_push true
git adr config adr.sync.auto_pull true

For all configuration options, see references/configuration.md.

ADR Best Practices

When to Write an ADR

Write an ADR for decisions that are:

Significant: Affects architecture or design
Structural: Changes system organization
Hard to reverse: Would require substantial effort to change

What Makes a Good ADR

Clear context: Explains the situation and constraints
Explicit decision: States what was decided
Documented consequences: Lists positive, negative, and neutral effects
Alternatives considered: Shows options evaluated

Common Mistakes

Too detailed (specification, not decision)
Too brief (no context or rationale)
Not updating status when decisions change
Writing long after the decision was made

For complete guidance, see references/best-practices.md.

Progressive Loading Guide

Load reference files based on user intent:

| User Intent | Load File | |-------------|-----------| | "Create an ADR" | references/formats/{template}.md | | "What commands are available?" | references/commands.md | | "Configure git-adr" | references/configuration.md | | "What is an ADR?" | references/best-practices.md | | "Set up for my team" | references/workflows.md | | "Find decisions about X" | references/search-patterns.md | | "Record this decision" | workflows/decision-capture.md | | "What did we decide" | workflows/decision-recall.md |

ADR Content Generation

When generating ADR content:

Read the project's configured format
Load the corresponding template from references/formats/
Ask clarifying questions if context is insufficient:
- What problem are you solving?
- What alternatives did you consider?
- What are the constraints?
Fill the template with the gathered information
Execute the command to create the ADR

Content Quality Checklist

Before creating an ADR, ensure:

[ ] Context explains the situation clearly
[ ] Decision is explicitly stated
[ ] Consequences are categorized (positive/negative/neutral)
[ ] Alternatives were considered (for MADR format)
[ ] Status is appropriate (proposed/accepted)

Reference Files

| File | Purpose | |------|---------| | references/commands.md | Full command documentation | | references/configuration.md | All config options | | references/best-practices.md | ADR writing guidance | | references/workflows.md | Common workflow patterns | | references/search-patterns.md | Natural language → search mapping | | references/formats/madr.md | MADR template | | references/formats/nygard.md | Nygard template | | references/formats/y-statement.md | Y-Statement template | | references/formats/alexandrian.md | Alexandrian template | | references/formats/business-case.md | Business Case template | | references/formats/planguage.md | Planguage template | | workflows/session-start.md | Auto-context loading behavior | | workflows/decision-capture.md | Guided ADR creation workflow | | workflows/decision-recall.md | Find past decisions workflow |