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:

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

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

For format templates, see references/formats/.

Creating ADRs

Workflow

1. Check format: Read adr.template config
2. Load template: Read appropriate format from references/formats/
3. Generate content: Fill template with user's context
4. 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:

ADR Content Generation

When generating ADR content:

1. Read the project's configured format
2. Load the corresponding template from references/formats/
3. Ask clarifying questions if context is insufficient:
   - What problem are you solving?
   - What alternatives did you consider?
   - What are the constraints?
4. Fill the template with the gathered information
5. 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