learn

Learn — Pattern Discovery & Guardrails Update

Scan the codebase to discover recurring coding patterns and update draft/guardrails.md with learned conventions and anti-patterns. This improves future quality command accuracy by reducing false positives and catching known-bad patterns.

Red Flags - STOP if you're:

• Writing to guardrails.md without reading the codebase first
• Learning a pattern from fewer than 3 occurrences
• Auto-promoting patterns to Hard Guardrails (requires human approval)
• Overwriting human-curated Hard Guardrails with learned patterns
• Learning patterns that contradict tech-stack.md ## Accepted Patterns
• Removing existing learned entries (only update or add)

Evidence over assumptions. Quantity over anecdote.

---

Arguments

• No arguments — full codebase pattern scan
• promote — review high-confidence learned patterns and offer promotion to Hard Guardrails or Accepted Patterns
• migrate — migrate ## Guardrails from workflow.md to guardrails.md (for existing projects)
• <path> — scan specific directory or file pattern

---

Step 0: Verify Draft Context

ls draft/ 2>/dev/null

If draft/ does not exist: STOP — "No Draft context found. Run /draft:init first."

---

Step 1: Load Existing Guardrails

1.1: Check for guardrails.md

ls draft/guardrails.md 2>/dev/null

If it exists, read it and internalize:

• Current Hard Guardrails (checked items)
• Current Learned Conventions (existing entries)
• Current Learned Anti-Patterns (existing entries)

1.2: Check for Legacy Guardrails (migration path)

If draft/guardrails.md does NOT exist:

1. Check draft/workflow.md for ## Guardrails section
2. If found, announce: "Found guardrails in workflow.md. Creating guardrails.md and migrating."
3. Create draft/guardrails.md using template from core/templates/guardrails.md
4. Copy checked guardrail items from workflow.md ## Guardrails into the Hard Guardrails section
5. Add a comment in workflow.md where ## Guardrails was:

   ## Guardrails
   
   > **Migrated** — Guardrails have moved to `draft/guardrails.md`. See that file for hard guardrails, learned conventions, and learned anti-patterns.
   

If migrate argument was given, stop here after migration. Otherwise, continue to pattern scanning.

1.3: Load Supporting Context

Read and follow core/shared/draft-context-loading.md for full Draft context. Key files:

• draft/.ai-context.md — Module boundaries, invariants, concurrency model
• draft/tech-stack.md — Frameworks, accepted patterns (do not learn patterns that duplicate these)
• draft/product.md — Product requirements

---

Step 2: Codebase Pattern Scan

2.1: Discover Source Files

# Find all source files (exclude vendored, generated, build artifacts)
find . -type f \( -name "*.ts" -o -name "*.tsx" -o -name "*.js" -o -name "*.jsx" \
  -o -name "*.py" -o -name "*.go" -o -name "*.rs" -o -name "*.java" \
  -o -name "*.cpp" -o -name "*.cc" -o -name "*.h" -o -name "*.hpp" \
  -o -name "*.rb" -o -name "*.php" -o -name "*.swift" -o -name "*.kt" \) \
  -not -path "*/node_modules/*" -not -path "*/vendor/*" -not -path "*/.git/*" \
  -not -path "*/dist/*" -not -path "*/build/*" -not -path "*/__pycache__/*" \
  -not -path "*/draft/*" \
  | head -500

If scope argument provided, filter to that path.

2.2: Analyze Pattern Dimensions

Scan the codebase across these dimensions, looking for recurring patterns (3+ occurrences):

Error Handling Conventions

• How errors are caught, logged, and propagated
• Custom error classes or error codes
• Try/catch patterns, error boundaries
• Retry and fallback strategies

Naming Conventions

• Variable, function, class naming styles beyond language defaults
• File naming patterns (kebab-case, PascalCase, etc.)
• Module/directory organization conventions

Architecture Patterns

• Import/dependency patterns (barrel exports, lazy loading)
• State management approaches
• API call patterns (centralized client, interceptors)
• Component composition patterns

Concurrency Patterns

• Async/await usage conventions
• Locking and synchronization approaches
• Queue and worker patterns
• Cancellation and timeout handling

Data Flow Patterns

• Validation placement (boundary vs deep)
• Serialization/deserialization conventions
• Caching strategies
• Data transformation pipelines

Testing Conventions

• Test file placement and naming
• Test structure (arrange/act/assert, given/when/then)
• Mock/stub conventions
• Fixture and factory patterns

Configuration Patterns

• Environment variable access patterns
• Feature flag patterns
• Config file conventions

2.3: Temporal Pattern Analysis

Detect patterns that are being phased out by the team:

1. Identify declining patterns — For each candidate pattern, use git blame to check the age of files containing it:
   • Old files (last modified >1 year ago): high occurrence of the pattern
   • New files (last modified <6 months ago): low or zero occurrence of the pattern
   • If occurrence ratio old:new is >3:1, flag as a declining pattern
2. Mark declining patterns — When writing to guardrails.md, add declining: true to the entry metadata:

   - **Declining:** yes — found in 8 old files (avg age 18mo), 1 new file (avg age 2mo). Being replaced by [newer pattern].
   

3. Do NOT propagate declining patterns — Quality commands should not flag absence of a declining pattern as inconsistency
4. Example: Old error handling style try/catch with manual logging found in files last modified >1 year ago, newer files use structured error middleware — the old style is declining, not a convention to enforce

Reference: Google large-scale changes (Rosie) — systematic detection of patterns being migrated away from.

2.4: Cross-Service Pattern Comparison (Monorepo)

When in a monorepo (detected by draft/service-index.md existing OR multiple draft/ directories OR presence of packages/, services/, apps/ directories):

1. Scan across services — Run pattern analysis in each service/package independently
2. Compare patterns for the same concern — For each pattern dimension (error handling, naming, etc.):
   • Does Service A use a different approach than Service B for the same concern?
   • Example: Service A uses Result<T, E> for error handling, Service B uses exceptions
3. Flag inconsistencies — Report cross-service divergences:

   Cross-service inconsistency: Error Handling
     services/auth/ → uses custom Result type (5 files)
     services/billing/ → uses thrown exceptions (8 files)
     Suggestion: standardize on one approach
   

4. Respect intentional differences — Do NOT flag inconsistencies when:
   • Services use different languages or frameworks
   • The pattern difference is documented in tech-stack.md or .ai-context.md
   • The services have fundamentally different runtime requirements

Reference: Google monorepo practices — consistent patterns across services reduce cognitive overhead and enable large-scale tooling.

2.5: Cross-Reference Existing Knowledge

For each candidate pattern:

1. Check tech-stack.md ## Accepted Patterns — if already documented there, skip (no duplication)
2. Check existing guardrails.md entries — if already learned, update evidence count and date
3. Check .ai-context.md — if described as architecture, skip (it's documented)
4. Verify consistency — sample 3+ instances and confirm they follow the same approach

---

2.6: Git History Signal Mining

Mine git commit history for pattern signals that code scanning misses. Run only if the project is a git repository.

git log --oneline --no-merges -500

Scan the output for recurring message patterns (3+ occurrences of the same type):

Commit pattern	Signal
fix: don't X / fix: never X	Team keeps violating X → anti-pattern candidate
refactor: replace X with Y	X is declining, Y is the replacement → mark X as declining: true
chore: enforce X / chore: add X check	X is being formalized → convention candidate
revert: followed by same topic 3+ times	That topic is consistently problematic → anti-pattern candidate

Rules:

• Do NOT add git-only signals as standalone entries. Use them only to adjust confidence of patterns already found in Step 2.2.
• If a pattern appears in both commit history AND code (3+ occurrences): increase confidence by one level.
• If a pattern appears only in commit history but not in current code: note as historically_recurring: true — do not add as active anti-pattern.

Recency weighting — for each candidate pattern from Step 2.2, check when the files containing it were last modified:

git log --follow --oneline -1 -- {file_containing_pattern}

• Modified within 90 days AND pattern persists → add recently_active: true to the entry
• Not modified in 12+ months → add stale: true — lower enforcement priority

---

2.7: Graph-Aware Severity Enrichment

If draft/graph/hotspots.jsonl exists, derive objective severity for all anti-pattern candidates based on the fanIn of files where the pattern was found.

For each anti-pattern candidate from Step 2.2:

1. Check if any evidence files appear in draft/graph/hotspots.jsonl
2. Take the highest fanIn value across all evidence files:
   • fanIn ≥ 10 → graph_severity: critical (breakage propagates to many callers)
   • fanIn 5–9 → graph_severity: high
   • fanIn 1–4 → graph_severity: medium
   • fanIn 0 or file not in hotspots.jsonl → graph_severity: low
3. If no graph data exists → graph_severity: unresolved

Collect all evidence files with fanIn ≥ 5 for the high_fanin_files field.

When graph_severity differs from the subjectively assigned severity, use graph_severity as the enforcement priority in quality commands — it is objective and reproducible.

---

Step 3: Apply Confidence Threshold

Follow the threshold from core/shared/pattern-learning.md:

Evidence	Confidence	Action
Found 1-2x	—	Skip (insufficient data)
Found 3-5x, all consistent	medium	Learn as convention or anti-pattern
Found >5x, all consistent, cross-verified	high	Learn + flag as promotion candidate
Found >5x but inconsistent	—	Do NOT learn (investigate inconsistency)

Distinguishing Conventions from Anti-Patterns

• Convention: Pattern is consistently applied AND does not cause bugs, security issues, or violations of documented invariants
• Anti-Pattern: Pattern is consistently applied BUT causes or risks bugs, security issues, performance problems, or invariant violations

---

Step 3.5: Pattern Conflict Detection

Before saving any new pattern, check for conflicts with existing entries:

1. Check against existing conventions — Does the new pattern contradict a learned convention?
2. Check against existing anti-patterns — Does the new pattern contradict a learned anti-pattern?
3. Check against Hard Guardrails — Does the new pattern violate a hard guardrail?

If conflict found:

• Do NOT silently save the new pattern
• Alert the user with both patterns side by side:

  CONFLICT DETECTED:
  
  Existing convention: "Use async/await for all async operations"
    Evidence: 12 files, high confidence, learned 2025-01-15
  
  New candidate: "Avoid async in database module — use callback style"
    Evidence: 4 files in src/db/, medium confidence
  
  These may both be valid (module-scoped exception) or one may be outdated.
  Options:
    [1] Keep both (new pattern is a scoped exception)
    [2] Replace existing with new (pattern has evolved)
    [3] Discard new (existing is correct)
  

• Wait for user input before proceeding

Reference: Google Code Health — conflicting patterns create confusion and should be resolved explicitly.

---

Step 3.7: External Benchmark Comparison

After discovering patterns, optionally compare project conventions against community standards for the detected language:

Language	Benchmarks
Go	Effective Go, Go Code Review Comments
Python	PEP 8, PEP 20, Google Python Style Guide
Java	Effective Java, Google Java Style Guide
TypeScript	typescript-eslint recommended rules
Rust	Rust API Guidelines, Clippy lints
C/C++	Google C++ Style Guide, C++ Core Guidelines

For each project convention that deviates from its language's community standard:

1. Note the deviation in the summary report (not as an anti-pattern — deviations may be intentional)
2. If the deviation is undocumented, suggest adding it to tech-stack.md ## Accepted Patterns with a rationale
3. Example: project uses snake_case for TypeScript functions (deviates from camelCase convention) — flag for documentation, not correction

Reference: Google Abseil Tips of the Week, language-specific style guides — deviations from community standards increase onboarding friction and should be documented even when intentional.

---

Step 4: Update guardrails.md

Follow the write procedure in core/shared/pattern-learning.md:

1. Read current draft/guardrails.md
2. For each new pattern: check for duplicates, then append
3. For existing patterns: update evidence count, confidence, last_verified
4. Update YAML frontmatter synced_to_commit

Cap enforcement: Maintain a maximum of 50 learned entries per section. If at capacity, replace the oldest medium confidence entry that has not been re-verified in 90+ days (per core/shared/pattern-learning.md).

Entry Format — Convention

### [Pattern Name]
- **Category:** error-handling | naming | architecture | concurrency | state-management | data-flow | testing | configuration
- **Confidence:** high | medium
- **Evidence:** Found in N files — `path/file1.ext:line`, `path/file2.ext:line`, `path/file3.ext:line`
- **Discovered at:** YYYY-MM-DD (when Draft first observed this pattern)
- **Established at:** YYYY-MM-DD (when the pattern entered the codebase, via git blame)
- **Last verified:** YYYY-MM-DD
- **Last active:** YYYY-MM-DD (when source files containing this pattern were last modified)
- **Discovered by:** draft:learn on YYYY-MM-DD
- **Description:** [What the pattern is and why it's intentional]

Entry Format — Anti-Pattern

### [Anti-Pattern Name]
- **Category:** security | reliability | performance | correctness | concurrency
- **Severity:** critical | high | medium
- **graph_severity:** critical | high | medium | low | unresolved  (fanIn-derived from Step 2.7; "unresolved" if no graph data)
- **high_fanin_files:** `path/file.go` (fanIn:12), `path/other.go` (fanIn:7)  (omit line if none meet fanIn ≥ 5)
- **Evidence:** Found in N files — `path/file1.ext:line`, `path/file2.ext:line`
- **Discovered at:** YYYY-MM-DD (when Draft first observed this pattern)
- **Established at:** YYYY-MM-DD (when the pattern entered the codebase, via git blame)
- **Last verified:** YYYY-MM-DD
- **Last active:** YYYY-MM-DD (when source files containing this pattern were last modified)
- **recently_active:** true | false  (true if any evidence file modified within 90 days)
- **stale:** true | false  (true if all evidence files unmodified for 12+ months)
- **Discovered by:** draft:learn on YYYY-MM-DD
- **Description:** [What the pattern is and why it's problematic]
- **Suggested fix:** [Brief description of the correct approach]

---

Step 5: Promotion Workflow (when promote argument given)

Review all learned patterns with confidence: high and present promotion candidates:

Pattern promotion candidates:

1. [Convention] "Centralized API client pattern" (high confidence, 12 files)
   → Promote to: tech-stack.md ## Accepted Patterns? [y/n]

2. [Convention] "Error boundary at route level" (high confidence, 8 files)
   → Promote to: Hard Guardrail (enforce always)? [y/n]

3. [Anti-Pattern] "Unguarded .env access" (high confidence, 6 files)
   → Promote to: Hard Guardrail (enforce always)? [y/n]

For each promoted pattern:

• Convention → Accepted Pattern: Append to draft/tech-stack.md ## Accepted Patterns and remove from guardrails.md Learned Conventions
• Convention → Hard Guardrail: Move from Learned Conventions to Hard Guardrails section (as checked [x] item)
• Anti-Pattern → Hard Guardrail: Move from Learned Anti-Patterns to Hard Guardrails section (as checked [x] item)

---

Step 6: Generate Summary Report

Display results to the user:

/draft:learn complete

Scanned: N source files across M directories
Duration: ~Xs

Results:
  New conventions learned:     N  [list names]
  New anti-patterns learned:   N  [list names]
  Existing patterns updated:   N  [list names]
  Skipped (insufficient data): N
  Skipped (already documented): N

Promotion candidates (high confidence):
  N patterns ready for promotion — run /draft:learn promote to review

Updated: draft/guardrails.md

---

How Quality Commands Use guardrails.md

After /draft:learn populates guardrails.md, all quality commands automatically:

Section	Quality Command Behavior
Hard Guardrails (checked)	Flag violations as issues
Learned Conventions	Skip these patterns during analysis (not bugs)
Learned Anti-Patterns	Always flag these patterns as bugs
Unchecked Hard Guardrails	Ignore (not enforced)

This creates a continuous improvement loop:

1. Quality command runs → discovers patterns → updates guardrails.md
2. Next quality command run → reads updated guardrails.md → fewer false positives, catches known-bad patterns
3. /draft:learn promote → graduates stable patterns to permanent status

---

Anti-Patterns

Don't	Instead
Learn from <3 occurrences	Require minimum 3 consistent instances
Auto-promote to Hard Guardrails	Always require human approval for promotion
Overwrite human-curated entries	Learned patterns complement, never replace
Learn framework defaults as conventions	Only learn project-specific patterns
Remove entries on re-scan	Update evidence/dates, never delete
Learn from test/mock code	Focus on production source code