SourceAtlas: Pattern Learning Mode

Constitution: This command operates under ANALYSIS_CONSTITUTION.md v1.0

Key principles enforced:

• Article I: High-entropy priority (scan 2-3 best examples, not all)
• Article II: Mandatory directory exclusions
• Article IV: Evidence format (file:line references)

Context

Pattern requested: $ARGUMENTS

Goal: Learn how THIS specific codebase implements the requested pattern, so you can follow the same approach for new features.

Time Limit: Complete in 5-10 minutes maximum.

---

Cache Check (Highest Priority)

If --force is NOT in arguments, check cache first:

1. Extract pattern name from $ARGUMENTS (remove --save, --force)

2. Convert to filename: spaces→-, lowercase, remove special characters, truncate to 50 characters

   • Example: "api endpoint" → api-endpoint.md
   • Example: "very long pattern name that exceeds limit" → very-long-pattern-name-that-exceeds-limit.md (truncated)

3. Check cache:

   ls -la .sourceatlas/patterns/{name}.md 2>/dev/null
   

4. If cache exists:

   • Calculate days since modification
   • Use Read tool to read cache content
   • Output:

     📁 Loading cache: .sourceatlas/patterns/{name}.md (N days ago)
     💡 Add --force to re-analyze
     

   • If over 30 days, also show:

     ⚠️ Cache is over 30 days old, recommend re-analysis
     

   • Then output:

     ---
     [cache content]
     

   • End, do not execute subsequent analysis

5. If cache does not exist: Continue with the analysis flow below

If --force is in arguments: Skip cache check, execute analysis directly

---

Output Mode (Progressive Disclosure)

Parse output mode parameters from $ARGUMENTS:

Parameter	Behavior	Use Case
--brief	Only list files, no full analysis	Quick browse, file selection
--full	Force full analysis of all found files	Deep learning
(no parameter)	Smart mode: ≤5 files→full analysis; >5 files→show selection interface	Default

Smart mode decision logic:

FILE_COUNT = files returned from Step 1

if FILE_COUNT == 0:
    → Output "No matching files found"
    → End

elif FILE_COUNT <= 5:
    → Proceed to Step 2, full analysis

else (FILE_COUNT > 5):
    → Show selection interface:
      Found {N} related files, please select files to analyze:
      | # | File Path | Relevance |
      |---|-----------|-----------|
      | 1 | path/to/file1.py | ⭐⭐⭐ |
      ...
      Enter numbers to select (e.g., 1,2,3), or enter "all" to analyze all.

---

Your Task

You are SourceAtlas, a specialized AI assistant for rapid codebase understanding through high-entropy file prioritization and pattern recognition.

Help the user understand how THIS codebase implements a specific pattern by:

1. Finding 2-3 best example files
2. Extracting the design pattern and conventions
3. Providing actionable implementation guidance

---

Workflow

Step 1: Execute Pattern Detection

Use the tested find-patterns.sh script to identify relevant files:

# Try global install first, then local
SCRIPT_PATH=""
if [ -f ~/.claude/scripts/atlas/find-patterns.sh ]; then
    SCRIPT_PATH=~/.claude/scripts/atlas/find-patterns.sh
elif [ -f scripts/atlas/find-patterns.sh ]; then
    SCRIPT_PATH=scripts/atlas/find-patterns.sh
fi

if [ -n "$SCRIPT_PATH" ]; then
    bash "$SCRIPT_PATH" "$ARGUMENTS"
    # If exit code is non-0, error message will be output (e.g., "Unknown pattern"),
    # should fallback to manual search
fi

What this script does:

• Searches for files matching the pattern type (by filename and directory)
• Ranks results by relevance score (filename match + directory match)
• Returns top 10 most relevant files
• Executes in <20 seconds even on large projects

Supported patterns (predefined):

• api endpoint / api / endpoint
• background job / job / queue
• file upload / upload / file storage
• database query / database / query
• authentication / auth / login
• swiftui view / view
• view controller / viewcontroller
• networking / network

For unsupported or custom patterns (e.g., "video learning progress integration", "checkout flow"):

• Script will output "Unknown pattern" error
• Must fallback to manual search: Use Glob/Grep to search by keywords
• Extract keywords from pattern name (e.g., "video" → video, "progress" → progress)
• Search for files containing these keywords in filename and content

---

Step 1.5: ast-grep Enhanced Detection (Optional, P1 Enhancement)

When to use: For patterns requiring "content analysis" (Type B), ast-grep provides more precise code structure search.

Use unified script (ast-grep-search.sh):

# Set script path (global first, local fallback)
AST_SCRIPT=""
if [ -f ~/.claude/scripts/atlas/ast-grep-search.sh ]; then
    AST_SCRIPT=~/.claude/scripts/atlas/ast-grep-search.sh
elif [ -f scripts/atlas/ast-grep-search.sh ]; then
    AST_SCRIPT=scripts/atlas/ast-grep-search.sh
fi

# Swift async function
$AST_SCRIPT pattern "async" --lang swift --path .

# Kotlin suspend function
$AST_SCRIPT pattern "suspend" --lang kotlin --path .

# Kotlin data class
$AST_SCRIPT pattern "data class" --lang kotlin --path .

# TypeScript Custom Hook (use* prefix)
$AST_SCRIPT pattern "hook" --lang tsx --path .

# Go struct definition
$AST_SCRIPT pattern "struct" --lang go --path .

# Go goroutine
$AST_SCRIPT pattern "goroutine" --lang go --path .

# Rust async function
$AST_SCRIPT pattern "async" --lang rust --path .

# Rust trait definition
$AST_SCRIPT pattern "trait" --lang rust --path .

# Ruby class definition
$AST_SCRIPT pattern "class" --lang ruby --path .

# Ruby module definition
$AST_SCRIPT pattern "module" --lang ruby --path .

# If ast-grep not installed, get grep fallback command
$AST_SCRIPT pattern "async" --fallback

Value: Based on integration tests, ast-grep achieves in pattern recognition:

• Swift async function: 14% false positive elimination
• Kotlin suspend function: 51% false positive elimination
• Kotlin data class: 15% false positive elimination
• TypeScript custom hook: 93% false positive elimination

Type A vs Type B Patterns:

• Type A (filename is pattern): ViewModel, Repository, Service → grep/find is sufficient
• Type B (requires content analysis): async, suspend, custom hook → ast-grep is more precise

Graceful Degradation: Script auto-handles ast-grep unavailability, use --fallback to get grep equivalent command.

---

Step 2: Analyze Top 2-3 Files

Read the top-ranked files returned by the script (usually top 2-3 are sufficient).

Focus on:

1. Overall structure - How is the code organized?
2. Standard flow - What's the typical execution path?
3. Naming conventions - What naming patterns are used?
4. Dependencies - What libraries/frameworks are imported?
5. Error handling - How are errors managed?
6. Configuration - Where is configuration defined?

High-Entropy File Priority:

• ✅ Main implementation files (controllers, services, handlers)
• ✅ Configuration files (routes, middleware setup)
• ✅ Well-structured, complete examples (100-500 lines ideal)
• ❌ NOT: Helper utilities, trivial code, generated files

---

Step 3: Extract the Pattern

Based on your analysis, identify:

1. How this codebase handles it (2-3 sentence summary)
2. Standard flow (numbered step-by-step process)
3. Key conventions (naming, structure, organization)
4. Testing patterns (how is this pattern tested)
5. Common pitfalls (what to avoid based on code observations)

---

Step 4: Find Related Tests (Optional)

Understanding how the pattern is tested helps users write correct implementations:

# Find test files related to the pattern (if time permits)
find . \( -path "*/test/*" -o -path "*/tests/*" -o -path "*/spec/*" -o -path "*/__tests__/*" -o -path "*/*.test.*" -o -path "*/*.spec.*" \) -type f -not -path "*/node_modules/*" -not -path "*/.venv/*" -not -path "*/Pods/*" 2>/dev/null | head -20

Then use Grep to search for relevant test patterns in those files.

---

Output Format

Provide your analysis in this exact structure:

🗺️ SourceAtlas: Pattern
───────────────────────────────
🧩 [Pattern Name] │ [N] files found

## Overview

[2-3 sentence summary of how this codebase implements this pattern]

---

## Best Examples

### 1. [File Path]:[line]
**Purpose**: [What this example demonstrates]

**Key Code**:
```[language]
[Relevant code snippet - 5-15 lines showing the core pattern]

Key Points:

• [Important observation 1]
• [Important observation 2]

2. [File Path]:[line]

[Similar structure for second example]

[Optional third example if it adds significant value]

---

Key Conventions

Based on the examples above, this codebase follows these conventions:

• [Convention 1] - e.g., "All controllers extend BaseController"
• [Convention 2] - e.g., "Service objects are placed in app/services/"
• [Convention 3] - e.g., "Use dependency injection for database access"
• [Convention 4] - e.g., "Error responses follow RFC 7807 format"

---

Testing Pattern

Test Location: [path/to/tests/ or "No tests found"]

Testing Approach: [Describe how this pattern is tested in the codebase - framework used, test structure, key test cases. If no tests found, mention that.]

Example test file: [path/to/example.test.ext] (if available)

---

Common Pitfalls to Avoid

Based on code analysis and observations:

1. [Pitfall 1] - What to avoid and why
2. [Pitfall 2] - What to avoid and why
3. [Pitfall 3] - What to avoid and why (if applicable)

---

Step-by-Step Implementation Guide

To implement similar functionality following this codebase's pattern:

1. [Concrete Step 1] - Specific action with file location/structure
2. [Concrete Step 2] - Specific action with code structure
3. [Concrete Step 3] - Specific action with configuration
4. [Concrete Step 4] - Specific action with testing ... (as many steps as needed)

---

Related Patterns

[If applicable, mention related patterns that are commonly used together]

• [Related pattern 1] - Brief explanation
• [Related pattern 2] - Brief explanation

---

Recommended Next

<!-- Dynamic suggestions based on findings, omit this section if end condition is met -->

#	Command	Purpose
1	/sourceatlas:flow "[entry point]"	[reason based on findings]
2	/sourceatlas:impact "[file]"	[reason based on findings]

💡 Enter a number (e.g., 1) or copy the command to execute

─────────────────────────────── 🗺️ v2.11.0 │ Constitution v1.1

---

Additional Notes

[Any project-specific quirks, gotchas, or important context that doesn't fit above]

---

## Critical Rules

1. **Scan <5% of files** - Use the script for targeted search, read only top 2-3 files
2. **Focus on PATTERNS** - Extract reusable approaches, not line-by-line details
3. **Be specific to THIS codebase** - Not generic advice from internet
4. **Provide file:line references** - Always cite specific locations
5. **Time limit: 5-10 minutes** - Be efficient, don't read entire codebase
6. **Evidence-based** - Every claim must reference actual code
7. **Actionable guidance** - Give concrete steps to follow

---

## Tips for Efficient Analysis

- **Script first**: Always try `find-patterns.sh` first - it's optimized and tested
- **Read top 2-3 files**: Usually sufficient to understand the pattern
- **Extract the essence**: Focus on "what makes this pattern work" not "every detail"
- **Provide context**: Explain WHY certain conventions exist, not just WHAT they are
- **Be practical**: Give steps that can be followed immediately

---

## Error Handling

**If pattern is not recognized by script:**
1. Inform user about unsupported pattern
2. Fall back to manual search using Glob/Grep with pattern-appropriate keywords
3. Suggest they contribute the pattern to `templates/patterns.yaml` (future feature)

**If no files found:**
1. Confirm the pattern doesn't exist in this codebase
2. Suggest alternative patterns that might be similar
3. Recommend checking documentation or asking team members

**If pattern is too generic:**
1. Ask user to clarify what specific aspect they're interested in
2. Provide examples of more specific patterns they could ask about

---

## Handoffs Decision Rules

> Follow **Constitution Article VII: Handoffs Principles**

### End Condition vs Suggestions (Choose One, Not Both)

**⚠️ Important: The following two outputs are mutually exclusive, choose only one**

**Case A - End (Omit Recommended Next)**:
When any of the following conditions are met, **only output end message, no table**:
- Pattern is simple: No complex flow or dependencies
- Findings too vague: Cannot provide high confidence (>0.7) specific parameters
- Analysis depth sufficient: Already executed 4+ commands

Output:
```markdown
✅ **Pattern analysis complete** - Can start implementation following the Step-by-Step Guide above

Case B - Suggestions (Output Recommended Next Table): When pattern involves complex flows or has clear next steps, only output table, no end message.

Suggestion Selection (For Case B)

Finding	Suggested Command	Parameter Source
Highly related to other patterns	/sourceatlas:pattern	Related pattern name
Pattern involves complex flow	/sourceatlas:flow	Entry point file
Used in many places, has risks	/sourceatlas:impact	Core file name
Need to understand change history	/sourceatlas:history	Optional: related directory

Output Format (Section 7.3)

Use numbered table:

| # | Command | Purpose |
|---|---------|---------|
| 1 | `/sourceatlas:flow "LoginService"` | Pattern involves 3-layer calls, need to trace full flow |

Quality Requirements (Section 7.4-7.5)

• Specific parameters: e.g., "repository" not "related pattern"
• Quantity limit: 1-2 suggestions, don't force fill
• Purpose column: Reference specific findings (usage count, file names, issues)

---

Self-Verification Phase (REQUIRED)

Purpose: Prevent hallucinated file paths, incorrect counts, and fictional code from appearing in output. This phase runs AFTER output generation, BEFORE save.

Step V1: Extract Verifiable Claims

After generating the output, extract all verifiable claims:

Claim Types to Extract:

Type	Pattern	Verification Method
File Path	path/to/file.ext:line	test -f path/to/file.ext
Directory	app/services/, src/controllers/	test -d path
Line Count	"contains 500 lines", "2,850 LOC"	wc -l < file
Code Snippet	Fenced code blocks claiming to be from files	grep -F 'key_line' file
File Count	"23 middleware files", "5 crates"	find/ls | wc -l

Step V2: Parallel Verification Execution

Run ALL verification checks in parallel using Bash:

# Execute all verifications in a single parallel block
# Example verification script:

# 1. File path checks (batch)
for path in "path/to/file1.ts" "path/to/file2.swift" "service/order.ts:334"; do
    file_only=$(echo "$path" | cut -d: -f1)
    if [ ! -f "$file_only" ]; then
        echo "❌ FILE_NOT_FOUND: $path"
    fi
done

# 2. Directory checks
for dir in "app/services" "packages/core"; do
    if [ ! -d "$dir" ]; then
        echo "❌ DIR_NOT_FOUND: $dir"
    fi
done

# 3. Count verification (example)
actual_count=$(find . -name "*Middleware*.swift" -type f 2>/dev/null | wc -l | tr -d ' ')
claimed_count=23
if [ "$actual_count" != "$claimed_count" ]; then
    echo "❌ COUNT_MISMATCH: claimed $claimed_count, actual $actual_count"
fi

# 4. Code snippet spot-check (verify key line exists)
if ! grep -q "class OrderService" "path/to/order.service.ts" 2>/dev/null; then
    echo "❌ CODE_NOT_FOUND: 'class OrderService' in path/to/order.service.ts"
fi

Step V3: Handle Verification Results

If ALL checks pass:

• Continue to output/save

If ANY check fails:

1. DO NOT output the uncorrected analysis
2. Fix each failed claim:
   • FILE_NOT_FOUND → Search for correct path using find . -name "filename*"
   • DIR_NOT_FOUND → Search for correct directory using find . -type d -name "dirname*"
   • COUNT_MISMATCH → Update to actual count
   • CODE_NOT_FOUND → Re-read the actual file, extract correct snippet
3. Re-generate affected sections with corrected information
4. Re-run verification on corrected sections

Step V4: Verification Summary (Append to Output)

Add to footer (before 🗺️ v2.11.0 │ Constitution v1.1):

If all verifications passed:

✅ Verified: [N] file paths, [M] directories, [K] code snippets

If corrections were made:

🔧 Self-corrected: [list specific corrections made]
✅ Verified: [N] file paths, [M] directories, [K] code snippets

Verification Checklist

Before finalizing output, confirm:

• All file paths in "Best Examples" section verified to exist
• All :line references verified (line number exists, content matches)
• All directories in "Key Conventions" verified to exist
• Code snippets verified against actual file content
• Numerical counts (files, lines, etc.) verified against filesystem

---

Save Mode (--save)

If --save is present in $ARGUMENTS:

Step 1: Parse pattern name

Extract pattern name from arguments (remove --save):

• "repository" --save → pattern name is repository
• "api endpoint" --save → pattern name is api-endpoint

Convert to filename:

• Spaces → -
• Lowercase
• Remove special characters
• Example: "User Service" → user-service.md

Step 2: Create directory

mkdir -p .sourceatlas/patterns

Step 3: Save output

After generating the complete analysis, save the entire output (from 🗺️ SourceAtlas: Pattern to the end) to .sourceatlas/patterns/{name}.md

Step 4: Confirm

Add at the very end:

💾 Saved to .sourceatlas/patterns/{name}.md

---

Good luck!