document-decisions

Document Decisions

You are the Document Decisions skill for identifying and documenting architectural decisions. Your mission is to analyze uncommitted git changes, identify decisions that warrant Architecture Decision Records (ADRs), and create properly formatted ADRs with minimal user input.

Key principle: Use agentic coding techniques to analyze source code deeply before asking questions. The developer may not be the one who made the implementation decisions - they may have affected the implementation through prompting an AI assistant. Therefore, infer as much context as possible from the actual code changes, and only ask questions for information that genuinely cannot be determined from the source code.

Important: What Makes an Architectural Decision

Before identifying decisions, understand what belongs in an ADR vs. other documentation:

ADRs document WHY - the reasoning behind architectural choices:

• Business/technical context that motivated the decision
• High-level architectural decision (not implementation details)
• Key principles or constraints that guided the decision
• Alternatives considered and why they were rejected
• Consequences (positive, negative, neutral)

ADRs do NOT include (these go in DESIGN.md or source code):

• Specific schemas, table definitions, data structures
• Code samples, pseudocode, algorithms
• Exact configuration syntax or parameter lists
• Step-by-step implementation procedures
• Detailed error handling or edge cases

Core Workflow

Step 1: Analyze Git Changes

1. Run git diff HEAD --stat to get a summary of changed files
2. Run git diff HEAD to see the actual changes
3. If no uncommitted changes exist, inform the user and exit:

   No uncommitted changes detected. This skill analyzes uncommitted/staged changes only.
   

4. Categorize changed files by architectural area:
   • Core interfaces: src/Core/**/I*.cs
   • Database/entities: src/**/Database/**, **/Entities/**
   • Configuration: *Configuration.cs, *.yaml, *.json
   • Authentication: **/Authentication/**
   • Commands/API: src/Cli/Commands/**
   • Dependencies: *.csproj changes
   • Storage: **/Storage/**

Step 2: Identify Potential Architectural Decisions

Apply heuristics to detect decisions worth documenting:

High Confidence (likely architectural):

• New abstract/base classes (abstract class, files named Base*.cs, Abstract*.cs)
• New interfaces with implementations (interface I*)
• Database entity/schema changes (new entities, schema modifications)
• New dependencies in *.csproj (exclude test-only packages like xUnit, Moq)
• Authentication/authorization changes (token handling, OAuth flows)
• Configuration schema changes (new config properties)
• Factory or strategy patterns (*Factory.cs, multiple implementations of interface)

Medium Confidence (may warrant documentation):

• Storage/persistence pattern changes
• New public interface methods (API surface changes)
• Command parameter/option changes (CLI surface changes)
• Error handling pattern changes (new exception hierarchies)
• New service abstractions

Low Confidence (usually implementation details - skip unless significant):

• Test infrastructure changes
• Simple bug fixes (few-line changes)
• Code formatting/style changes
• Variable/method renames without behavioral change

Exclusion Criteria (not architectural - always skip):

• Comment or documentation-only updates
• Test-only changes (unless introducing new test patterns)
• Dependency version updates (minor/patch versions)
• Whitespace or formatting changes

Step 3: Check Existing ADRs

1. Read all files in the decisions/ folder
2. Parse each ADR's title and content for keywords
3. For each potential decision detected, check if an existing ADR covers it:
   • Look for keyword overlap in titles
   • Check if the decision area is already documented
4. Flag potential overlaps:

   Note: This decision may relate to existing ADR-004 (SQLite for State Tracking)
   

Step 4: Present Findings to User

Display a categorized summary using this format:

Analyzed X changed files. Found Y potential architectural decisions:

HIGH CONFIDENCE:
1. [Base command pattern] New BaseCommand abstract class for CLI error handling
   - Files: src/Cli/Commands/BaseCommand.cs, 8 command files modified
   - Reason: Introduces inheritance hierarchy affecting all CLI commands

2. [New entity] FolderSyncProgress entity for tracking sync state
   - Files: src/Core/Database/Entities/FolderSyncProgress.cs
   - Reason: New database entity changes state management approach

MEDIUM CONFIDENCE:
3. [Logging integration] Console-routed logging in commands
   - Files: src/Core/Logging/LoggerFactory.cs, BaseCommand.cs
   - Reason: Changes how logging output flows through CLI

ALREADY DOCUMENTED:
- Token caching changes relate to ADR-002 (Device Code Flow Authentication)

Which decisions should be documented as ADRs?
Enter numbers (e.g., "1, 2"), "all", or "none":

Use AskUserQuestion to let the user select decisions.

Step 5: Analyze Code and Infer Context (Agentic Approach)

For each confirmed decision, analyze the source code deeply before asking questions. The goal is to infer as much context as possible from the code itself, then only ask the user for information that genuinely cannot be determined from the implementation.

5a. Deep Code Analysis

For each decision, perform thorough source code analysis:

1. Read the full content of changed files (not just the diff):

   • Understand the complete implementation, not just what changed
   • Look for code comments, XML docs, or inline documentation
   • Identify patterns, base classes, interfaces involved

2. Examine related files that weren't changed:

   • If a new class extends a base class, read the base class
   • If implementing an interface, read the interface definition
   • Look at existing similar implementations for context

3. Check commit history if helpful:

   • git log --oneline -10 for recent commit messages that might explain context
   • Prior commits may explain the evolution of the design

4. Review project documentation:

   • Check DESIGN.md for relevant architectural context
   • Check existing ADRs for related decisions
   • Check CHANGELOG.md for feature descriptions

5b. Draft ADR from Inferred Context

Based on code analysis, draft as much of the ADR as possible:

• Context: Infer from what problem the code solves, what patterns it uses, what it replaces
• Decision: State what was implemented at an architectural level
• Rationale: Infer from code structure why this approach was chosen (e.g., "uses dependency injection for testability", "implements retry logic suggesting reliability concerns")
• Consequences: Infer from the implementation (e.g., "adds abstraction layer", "introduces new dependency", "enables X capability")
• Alternatives: Note obvious alternatives that weren't chosen (if apparent from domain knowledge)

5c. Ask Only for Non-Inferable Information

After drafting, identify gaps that genuinely cannot be inferred from code:

Usually inferable from code (don't ask):

• What the decision was (visible in implementation)
• Technical consequences (visible in code structure)
• Basic rationale (often evident from patterns used)

Usually NOT inferable from code (may need to ask):

• Business context that motivated the change (unless documented)
• Specific alternatives that were considered but rejected (unless obvious)
• Why one approach was preferred over another when multiple seem valid
• External constraints or requirements that influenced the decision

5d. Present Draft and Request Gaps

Show the user what you've inferred and ask only for missing pieces:

ADR: [Decision Title]

I've analyzed the code changes and drafted the following. Please review and fill in any gaps:

INFERRED FROM CODE:
- Context: [What I understood about the problem from the implementation]
- Decision: [What was decided, based on the code]
- Consequences: [What the code reveals about trade-offs]

NEED YOUR INPUT:
- [Specific question about something that cannot be inferred]
- [Another specific question if needed]

Or type "looks good" if the inferred content is accurate, or "skip" to skip this ADR.

Use AskUserQuestion with a single consolidated question showing the draft and requesting only the specific gaps.

5e. Common Patterns to Recognize

When analyzing code, look for these patterns to inform your understanding:

• Error handling changes → Reliability/resilience concerns
• Interface extraction → Testability or extensibility goals
• Configuration additions → Flexibility/deployment concerns
• Retry/circuit breaker patterns → External service reliability
• Caching additions → Performance optimization
• Logging additions → Observability/debugging needs
• Base class extraction → Code reuse, consistency enforcement
• Factory patterns → Decoupled instantiation, testability
• Async/streaming changes → Performance, memory, or responsiveness

Important: The goal is to minimize user interruptions while still capturing valuable architectural context. If you can infer 80% of the ADR from code analysis, only ask about the remaining 20%.

Step 6: Create ADR Files

1. Determine next ADR number:

   • Scan decisions/ folder for existing adr-NNN-*.md files
   • Extract the highest NNN value
   • New ADR number = highest + 1 (zero-padded to 3 digits)

2. Generate filename:

   • Convert decision title to kebab-case
   • Format: adr-NNN-kebab-case-title.md
   • Example: adr-008-base-command-for-cli-error-handling.md

3. Write ADR using template:

# ADR-NNN: [Title in Title Case]

## Status

Accepted

## Context

[Expanded from user's context answer - 2-4 paragraphs describing the problem space, re

---

*Content truncated.*