ADR: Draft ADR from natural language description (adr_draft)

[rshade]

Priority: P2 - Medium Priority

Part of Epic: #289
Estimated Effort: 6-8 hours
Phase: 3 - AI-Assisted Features

Problem Statement

Writing ADRs takes time and many developers skip them because of the effort involved. AI-assisted drafting can lower the barrier by generating a structured ADR from a natural language description of the decision.

Proposed Solution

Implement adr_draft tool that:

1. Takes natural language description of a decision
2. Generates structured ADR with all required sections
3. Suggests related existing ADRs to reference
4. Proposes consequences based on similar decisions

Implementation Guidance

Tool Schema

const AdrDraftArgsSchema = z.object({
  directory: z.string().optional()
    .describe("Working directory"),
  description: z.string()
    .describe("Natural language description of the decision"),
  format: z.enum(["nygard", "madr", "madr-minimal"]).optional()
    .describe("Template format (uses project default)"),
});

Draft Result Interface

interface AdrDraftResult {
  suggestedTitle: string;
  draft: string;              // Full markdown content
  relatedAdrs: number[];      // Existing ADRs to consider referencing
  confidence: number;         // 0-1 confidence in the draft quality
  suggestions: string[];      // "Consider adding security implications"
}

Drafting Strategy

Structure Extraction:

// From: "We discussed using Redis for caching because PostgreSQL 
//        queries were getting slow. The team agreed this adds 
//        operational complexity but improves response times."

// Extract:
{
  context: "PostgreSQL queries were getting slow",
  decision: "Use Redis for caching",
  consequences: {
    positive: ["improves response times"],
    negative: ["adds operational complexity"]
  }
}

Section Generation:

1. Title: Extract core decision verb + subject
2. Context: Extract problem statement, triggers
3. Decision: Extract the choice made
4. Consequences: Extract trade-offs mentioned

Development Steps

1. Codebase Analysis

   • Review existing ADRs for pattern learning
   • Consider NLP approaches for extraction

2. Implementation

   • Implement text analysis for structure extraction
   • Generate section content
   • Match against existing ADRs
   • Format according to template

3. Testing Requirements

   • Test with various description styles
   • Test all output formats
   • Test related ADR detection
   • Target: 85-90%+ coverage

4. Linting & Validation

   make lint
   make test
   make build

Acceptance Criteria

Feature Complete:

• Extracts structure from natural language
• Generates complete ADR draft
• Suggests related ADRs
• Supports all template formats

Quality Gates:

• make lint passes with zero errors
• make test passes with 85-90%+ coverage
• make build completes successfully

Documentation:

• JSDoc comments for all public methods
• Update src/instructions.md

Example Usage

adr_draft({
  description: "We discussed using Redis for caching because PostgreSQL " +
               "queries were getting slow under load. The team agreed this " +
               "adds operational complexity but significantly improves " +
               "response times. We chose Redis over Memcached because of " +
               "persistence options."
})
// Returns:
// {
//   suggestedTitle: "Use Redis for Caching Layer",
//   draft: `# N. Use Redis for Caching Layer
//
// Date: 2025-01-04
//
// ## Status
//
// Proposed
//
// ## Context
//
// PostgreSQL queries were experiencing performance degradation under load,
// impacting API response times. The team needed a caching solution to
// reduce database load and improve user experience.
//
// ## Decision
//
// We will use Redis as our caching layer.
//
// Redis was chosen over Memcached because:
// - Redis offers persistence options for cache durability
// - Redis provides richer data structures
//
// ## Consequences
//
// **Positive:**
// - Significantly improved API response times
// - Reduced load on PostgreSQL database
//
// **Negative:**
// - Added operational complexity (new service to manage)
// - Additional infrastructure costs
// - Need to implement cache invalidation strategy
// `,
//   relatedAdrs: [2],  // ADR-2: Use PostgreSQL
//   confidence: 0.85,
//   suggestions: [
//     "Consider documenting the cache invalidation strategy",
//     "Reference ADR-2 (PostgreSQL) in the context"
//   ]
// }

References

• Epic: Epic: Architecture Decision Records (ADR) Tooling Support #289
• Depends on: Phase 1 tools, adr_search
• Key differentiator - saves significant ADR authoring time