ailang-sprint-executor

name	AILANG Sprint Executor
description	Execute approved sprint plans with test-driven development, continuous linting, progress tracking, and pause points. Use when user says "execute sprint", "start sprint", or wants to implement an approved sprint plan.

AILANG Sprint Executor

Execute an approved sprint plan with continuous progress tracking, testing, and documentation updates.

Quick Start

Most common usage:

# User says: "Execute the sprint plan in design_docs/20251019/M-S1.md"
# This skill will:
# 1. Validate prerequisites (tests pass, linting clean)
# 2. Create TodoWrite tasks for all milestones
# 3. Execute each milestone with test-driven development
# 4. Run checkpoint after each milestone (tests + lint)
# 5. Update CHANGELOG and sprint plan progressively
# 6. Pause after each milestone for user review

When to Use This Skill

Invoke this skill when:

• User says "execute sprint", "start sprint", "begin implementation"
• User has an approved sprint plan ready to implement
• User wants guided execution with built-in quality checks
• User needs progress tracking and pause points

Core Principles

1. Test-Driven: All code must pass tests before moving to next milestone
2. Lint-Clean: All code must pass linting before moving to next milestone
3. Document as You Go: Update CHANGELOG.md and sprint plan progressively
4. Pause for Breath: Stop at natural breakpoints for review and approval
5. Track Everything: Use TodoWrite to maintain visible progress
6. DX-First: Improve AILANG development experience as we go - make it easier next time

Multi-Session Continuity (NEW)

Sprint execution can now span multiple Claude Code sessions!

Based on Anthropic's long-running agent patterns, sprint-executor implements the "Coding Agent" pattern:

• Session Startup Routine: Every session starts with session_start.sh

  • Checks working directory
  • Reads JSON progress file (.ailang/state/sprint_<id>.json)
  • Reviews recent git commits
  • Validates tests pass
  • Prints "Here's where we left off" summary

• Structured Progress Tracking: JSON file tracks state

  • Features with passes: true/false/null (follows "constrained modification" pattern)
  • Velocity metrics updated automatically
  • Clear checkpoint messages
  • Session timestamps

• Pause and Resume: Work can be interrupted at any time

  • Status saved to JSON: not_started, in_progress, paused, completed
  • Next session picks up exactly where you left off
  • No loss of context or progress

For JSON schema details, see resources/json_progress_schema.md

Documentation URLs

When adding error messages, help text, or documentation links in code:

Website: https://sunholo-data.github.io/ailang/

Documentation Source: The website documentation lives in this repo at docs/

• Markdown files: docs/docs/ (guides, reference, etc.)
• Static assets: docs/static/
• Docusaurus config: docs/docusaurus.config.js

Common Documentation Paths:

• Language syntax: /docs/reference/language-syntax
• Module system: /docs/guides/module_execution
• Getting started: /docs/guides/getting-started
• REPL guide: /docs/guides/getting-started#repl
• Implementation status: /docs/reference/implementation-status

Full URL Example:

https://sunholo-data.github.io/ailang/docs/reference/language-syntax

Best Practices:

• Check that documentation URLs actually exist before using them in error messages or help text
• Look in docs/docs/ to verify the file exists locally
• Use ls docs/docs/reference/ or ls docs/docs/guides/ to find available pages

Available Scripts

scripts/session_start.sh <sprint_id>

NEW: Resume sprint execution across multiple sessions.

Usage:

# Start or resume a sprint
.claude/skills/sprint-executor/scripts/session_start.sh M-S1

What it does:

• Implements "Session Startup Routine" from Anthropic article
• Checks pwd (working directory)
• Loads JSON progress file (.ailang/state/sprint_<id>.json)
• Reviews recent git commits (last 3)
• Runs tests to verify clean state
• Shows feature progress summary (complete/in-progress/pending)
• Displays velocity metrics
• Prints "Here's where we left off" message

When to use:

• ALWAYS at the start of EVERY session continuing a sprint
• First thing after user says "continue sprint" or "resume M-S1"
• Provides context for multi-session work

Exit codes:

• 0 - Sprint ready to continue
• 1 - Progress file not found or tests failing

scripts/validate_prerequisites.sh

Validate prerequisites before starting sprint execution.

Usage:

.claude/skills/sprint-executor/scripts/validate_prerequisites.sh

Output:

Validating sprint prerequisites...

1/4 Checking working directory...
  ✓ Working directory clean

2/4 Checking current branch...
  ✓ On branch: dev

3/4 Running tests...
  ✓ All tests pass

4/4 Running linter...
  ✓ Linting passes

✓ All prerequisites validated!
Ready to start sprint execution.

Exit codes:

• 0 - All prerequisites pass
• 1 - One or more prerequisites fail

scripts/milestone_checkpoint.sh <milestone_name>

Run checkpoint after completing a milestone.

Usage:

.claude/skills/sprint-executor/scripts/milestone_checkpoint.sh "M-S1.1: Parser foundation"

Output:

Running checkpoint for: M-S1.1: Parser foundation

1/3 Running tests...
  ✓ Tests pass

2/3 Running linter...
  ✓ Linting passes

3/3 Files changed in this milestone...
 internal/parser/parser.go   | 125 ++++++++++++++++++
 internal/parser/parser_test.go | 89 +++++++++++++
 2 files changed, 214 insertions(+)

✓ Milestone checkpoint passed!
Ready to proceed to next milestone.

Execution Flow

Phase 0: Session Resumption (for continuing sprints)

If this is NOT the first session for this sprint:

# ALWAYS run session_start.sh first!
.claude/skills/sprint-executor/scripts/session_start.sh <sprint-id>

This will:

• Load JSON progress file
• Show what's complete, in-progress, and pending
• Verify tests pass before continuing
• Print "Here's where we left off" summary

Then skip to Phase 2 to continue with the next milestone.

Phase 1: Initialize Sprint (first session only)

1. Read Sprint Plan

• Parse sprint plan document (e.g., design_docs/20251019/M-S1.md)
• Load JSON progress file (.ailang/state/sprint_<id>.json)
• Extract all milestones and tasks from JSON
• Note dependencies and acceptance criteria
• Identify estimated LOC and duration

2. Validate Prerequisites

Use the validation script:

.claude/skills/sprint-executor/scripts/validate_prerequisites.sh

Manual checks:

• Working directory clean: git status --short
• Current tests pass: make test
• Current linting passes: make lint
• On correct branch (usually dev)

If validation fails:

• Fix issues before starting
• Don't proceed with dirty working directory
• Don't start with failing tests or linting

3. Create Todo List

Use TodoWrite to create tasks:

• Extract all milestones from sprint plan
• Mark first milestone as in_progress
• Keep remaining tasks as pending
• This provides real-time progress visibility

4. Initial Status Update

• Update sprint plan with "🔄 In Progress" status
• Add start timestamp
• Commit sprint plan update (optional)

5. Initial DX Review

• Review what tasks we're about to do
• Consider what tools/helpers would make this sprint easier
• Small DX improvements (<30 min): Add them to the milestone plan immediately
  • Examples: Helper functions, test utilities, debug flags, make targets
• Large DX improvements (>30 min): Create design doc in design_docs/planned/vX_Y/m-dx*.md
  • Examples: New skill, major refactor, architectural change
• Document DX improvement decisions in sprint plan

Phase 2: Execute Milestones

For each milestone in the sprint:

Step 1: Pre-Implementation

• Mark milestone as in_progress in TodoWrite
• Review milestone goals and acceptance criteria
• Identify files to create/modify
• Estimate LOC if not already specified

Step 2: Implement

During implementation, think about DX:

• Write implementation code following the task breakdown
• Follow design patterns from sprint plan
• Add inline comments for complex logic
• Keep functions small and focused

DX-aware implementation:

• If you're writing boilerplate, could it be a helper function?
• If you're debugging something, could a debug flag help?
• If you're looking things up repeatedly, should it be documented?
• If an error message confused you, would it confuse others?
• If a test is verbose, could test helpers make it cleaner?

Examples:

// ❌ Before DX thinking
if p.Errors() != nil {
    // Manually check each error...
}

// ✅ After DX thinking - Add helper
AssertNoErrors(t, p)  // Helper added for reuse

// ❌ Before DX thinking
// Manually inspecting tokens with fmt.Printf
fmt.Printf("cur=%v peek=%v\n", p.curToken, p.peekToken)

// ✅ After DX thinking - Add debug mode
// DEBUG_PARSER=1 automatically traces token flow

// ❌ Before DX thinking
return fmt.Errorf("parse error")

// ✅ After DX thinking - Actionable error
return fmt.Errorf("parse error at line %d: expected RPAREN after argument list, got %s. See docs/guides/parser_development.md#common-issues", p.curToken.Line, p.curToken.Type)

When to act on DX ideas:

• 🟢 Quick (<15 min): Do it now as part of this milestone
• 🟡 Medium (15-30 min): Note in TODO list, do at end of milestone if time allows
• 🔴 Large (>30 min): Note for design doc in reflection step

Step 3: Write Tests

⚠️ TDD REMINDER (M-TESTING Learning):

Consider writing tests BEFORE or ALONGSIDE implementation for:

• Complex algorithms (shrinking, generators, property evaluation)
• API integration (using unfamiliar packages like internal/eval)
• Error handling paths (multiple failure modes)

Benefits of TDD/Test-First:

• Discover API issues earlier (before writing 500 lines)
• Better design from testability constraints
• Catch bugs in development, not at checkpoint
• Example: Day 7 wrote 530 lines → 23 API errors. Tests first would find these at ~50 lines.

Standard Testing:

• Create/update test files (*_test.go)
• Aim for comprehensive coverage (all acceptance criteria)
• Include edge cases and error conditions
• Test both success and failure paths

Parser tests (M-DX9):

• Use helpers from internal/parser/test_helpers.go:
  • AssertNoErrors(t, p) - Check for parser errors
  • AssertLiteralInt(t, expr, 42) - Check integer literals
  • AssertIdentifier(t, expr, "name") - Check identifiers
  • AssertFuncCall(t, expr) - Check function calls
  • See full list in internal/parser/test_helpers.go
• Reference docs/guides/parser_development.md for test patterns
• Common gotchas documented in internal/ast/ast.go (e.g., int64 vs int)

Step 4: Verify Quality

Run checkpoint script:

.claude/skills/sprint-executor/scripts/milestone_checkpoint.sh "Milestone name"

Manual verification:

make test  # MUST PASS
make lint  # MUST PASS

CRITICAL: If tests or linting fail, fix immediately before proceeding.

Step 5: Update Documentation

Update CHANGELOG.md:

• What was implemented
• LOC counts (implementation + tests)
• Key design decisions
• Files modified/created

Create/update example files (CRITICAL - ALWAYS REQUIRED):

• Every new language feature MUST have a corresponding example file
• Create examples/feature_name.ail for the new feature
• Include comprehensive examples showing all capabilities
• Add comments explaining the behavior and expected output
• ⚠️ Test that examples actually work: ailang run examples/feature_name.ail
• ⚠️ Add warning headers to examples that don't work yet (use make flag-broken)
• Document example files created in CHANGELOG.md
• See CLAUDE.md "IMPORTANT: Example Files Required" section

Update sprint plan (markdown):

• Mark milestone as ✅
• Add actual LOC vs estimated
• Note any deviations from plan
• List example files created/updated

NEW: Update JSON progress file:

# Update feature status in .ailang/state/sprint_<id>.json
# Using jq for safe atomic updates:

SPRINT_ID="M-S1"
FEATURE_ID="M-S1.1"
ACTUAL_LOC=214

# Mark feature as passing
jq --arg id "$FEATURE_ID" \
   --argjson passes true \
   --argjson loc "$ACTUAL_LOC" \
   --arg completed "$(date -u +"%Y-%m-%dT%H:%M:%SZ")" \
   '(.features[] | select(.id == $id) | .passes) = $passes |
    (.features[] | select(.id == $id) | .actual_loc) = $loc |
    (.features[] | select(.id == $id) | .completed) = $completed' \
   ".ailang/state/sprint_${SPRINT_ID}.json" > /tmp/sprint_update.json

mv /tmp/sprint_update.json ".ailang/state/sprint_${SPRINT_ID}.json"

# Update velocity metrics
# (This can be automated - calculate from completed features)

Important: Only update the passes, actual_loc, completed, and notes fields. Do NOT modify description or acceptance_criteria (follows "constrained modification" pattern).

Step 6: DX Reflection

After each milestone, reflect on the development experience:

Ask yourself:

• What was painful during this milestone?
• What took longer than expected due to tooling gaps?
• What did we have to lookup multiple times?
• What errors/bugs could better tooling prevent?

Categorize DX improvements:

🟢 Quick wins (<15 min) - Do immediately:

• Add helper function to reduce boilerplate
• Add debug flag for better visibility
• Improve error message with actionable suggestion
• Add make target for common workflow
• Document pattern in code comments

🟡 Medium improvements (15-30 min) - Add to current sprint if time allows:

• Create test utility package
• Add validation script
• Improve CLI flag organization
• Add comprehensive examples

🔴 Large improvements (>30 min) - Create design doc:

• New skill for complex workflow
• Major architectural change
• New developer tool or subsystem
• Significant codebase reorganization

Document in milestone summary:

## DX Improvements (Milestone X)

✅ **Applied**: Added `AssertNoErrors(t, p)` test helper (5 min)
📝 **Deferred**: Created M-DX10 design doc for parser AST viewer tool (estimated 2 hours)
💡 **Considered**: Better REPL error messages (added to backlog)

Step 7: Pause for Breath

After each milestone:

• Show summary of what was completed
• Show current sprint progress (X of Y milestones done)
• Show velocity (LOC/day vs planned)
• Show DX improvements made/planned
• Ask user: "Ready to continue to next milestone?" or "Need to review/adjust?"
• If user says "pause" or "stop", save current state and exit gracefully

Phase 3: Finalize Sprint

When all milestones are complete:

1. Final Testing

make test                # Full test suite
make lint                # All linting
make test-coverage-badge # Coverage check

2. Documentation Review

• Verify CHANGELOG.md is complete
• Verify example files created and tested (CRITICAL)
  • Every new feature should have examples/feature_name.ail
  • Run make verify-examples to check all examples
  • Check that new examples are documented in CHANGELOG.md
• Verify sprint plan shows all milestones as ✅
• Update sprint plan with final metrics:
  • Total LOC (actual vs estimated)
  • Total time (actual vs estimated)
  • Velocity achieved
  • Test coverage achieved
  • Example files created (list them)
  • Any deviations from plan

3. Final Commit

git commit -m "Complete sprint: <sprint-name>

Milestones completed:
- <Milestone 1>: <LOC>
- <Milestone 2>: <LOC>

Total: <actual-LOC> LOC in <actual-time>
Velocity: <LOC/day>
Test coverage: <percentage>"

4. Summary Report

• Show sprint completion summary
• Compare planned vs actual (LOC, time, milestones)
• Highlight any issues or deviations
• Suggest next steps (new sprint, release, etc.)

5. DX Impact Summary

Consolidate all DX improvements made during sprint:

## DX Improvements Summary (Sprint M-XXX)

### Applied During Sprint
✅ **Test Helpers** (Day 2, 10 min): Added `AssertNoErrors()` and `AssertLiteralInt()` helpers
   - Impact: Reduced test boilerplate by ~30%
   - Files: internal/parser/test_helpers.go

✅ **Debug Flag** (Day 4, 5 min): Added `DEBUG_PARSER=1` for token tracing
   - Impact: Eliminated 2 hours of token position debugging
   - Files: internal/parser/debug.go

✅ **Make Target** (Day 6, 3 min): Added `make update-golden` for parser test updates
   - Impact: Simplified golden file workflow
   - Files: Makefile

### Design Docs Created
📝 **M-DX10**: Parser AST Viewer Tool (estimated 2 hours)
   - Rationale: Spent 45 min manually inspecting AST structures
   - Expected ROI: Save ~30 min per future parser sprint
   - File: design_docs/planned/v0_4_0/m-dx10-ast-viewer.md

📝 **M-DX11**: Unified Error Message System (estimated 4 hours)
   - Rationale: Error messages inconsistent across lexer/parser/type checker
   - Expected ROI: Easier debugging for AI and humans
   - File: design_docs/planned/v0_4_0/m-dx11-error-system.md

### Considered But Deferred
💡 **REPL history search**: Nice-to-have, low impact vs effort
💡 **Syntax highlighting**: Human-focused, AILANG is AI-first
💡 **Auto-completion**: Deferred until reflection system complete

### Total DX Investment This Sprint
- Time spent: 18 min (quick wins)
- Time saved: ~3 hours (estimated, based on future sprint projections)
- Design docs: 2 (total estimated effort: 6 hours for future sprints)
- **Net impact**: Positive ROI even in current sprint

Key Questions for Future:

• Which DX improvements should be prioritized next?
• Are there patterns in pain points (e.g., parser work always needs better debugging)?
• Should any DX improvements be added to "Definition of Done" for future sprints?

DX Improvement Patterns

Common DX improvements to watch for during sprints:

1. Repetitive Boilerplate → Helper Functions

Signals:

• Copying/pasting the same test setup code
• Same validation logic repeated across functions
• Common error handling patterns duplicated

Quick fixes (5-15 min):

• Extract to helper function in same package
• Add to *_helpers.go file
• Document with usage example
• Add tests for helper if complex

Example: M-DX9 added AssertNoErrors(t, p) after noticing parser test boilerplate.

2. Hard-to-Debug Issues → Debug Flags

Signals:

• Adding temporary fmt.Printf() statements
• Manually tracing execution flow
• Repeatedly inspecting internal state

Quick fixes (5-10 min):

• Add DEBUG_<SUBSYSTEM>=1 environment variable check
• Gate debug output behind flag (zero overhead when off)
• Document in CLAUDE.md or code comments

Example: M-DX9 added DEBUG_PARSER=1 for token flow tracing.

3. Manual Workflows → Make Targets

Signals:

• Running multi-step commands repeatedly
• Forgetting command flags or order
• Different team members using different commands

Quick fixes (3-5 min):

• Add make <target> with clear name
• Document what it does in make help
• Show example usage in relevant docs

Example: make update-golden for parser test golden files.

4. Confusing APIs → Documentation

Signals:

• Looking up API signatures multiple times
• Trial-and-error with function arguments
• Grep-diving to understand usage

Quick fixes (10-20 min):

• Add package-level godoc with examples
• Document common patterns in CLAUDE.md
• Add usage examples to function comments
• Create make doc PKG=<package> target if missing

Example: M-TESTING documented common API patterns in CLAUDE.md.

5. Poor Error Messages → Actionable Errors

Signals:

• Error doesn't explain what went wrong
• No suggestion for how to fix
• Missing context (line numbers, file names)

Quick fixes (5-15 min):

• Add context to error message
• Suggest fix or workaround
• Link to documentation if relevant
• Include values that triggered error

Example:

// ❌ Before
return fmt.Errorf("parse error")

// ✅ After
return fmt.Errorf("parse error at %s:%d: expected RPAREN, got %s. Did you forget to close the argument list? See: https://sunholo-data.github.io/ailang/docs/guides/parser_development#common-issues",
    p.filename, p.curToken.Line, p.curToken.Type)

6. Painful Testing → Test Utilities

Signals:

• Verbose test setup/teardown
• Repeated value construction
• Brittle test assertions

Quick fixes (10-20 min):

• Create test helper package (e.g., testctx/)
• Add value constructors (e.g., MakeString(), MakeInt())
• Add assertion helpers (e.g., AssertNoErrors())

Example: M-DX1 added testctx package for builtin testing.

DX ROI Calculator

When deciding whether to implement a DX improvement:

Time saved per use × Expected uses = Total savings
If Total savings > Implementation time + Maintenance → DO IT

Examples:

• Helper function: 2 min × 20 uses = 40 min saved, costs 10 min → ROI = 4x ✅
• Debug flag: 15 min × 5 uses = 75 min saved, costs 8 min → ROI = 9x ✅
• Documentation: 5 min × 30 uses = 150 min saved, costs 20 min → ROI = 7.5x ✅
• New skill: 30 min × 2 uses = 60 min saved, costs 120 min → ROI = 0.5x ❌ (create design doc for later)

Note: ROI compounds over time as more developers/sprints benefit!

Key Features

Continuous Testing

• Run make test after every file change
• Never proceed if tests fail
• Show test output for visibility
• Track test count increase

Parser test best practices (M-DX9):

• Use test helpers from internal/parser/test_helpers.go for cleaner assertions
• Print errors BEFORE t.Fatalf() or use AssertNoErrors(t, p) helper
• Reference docs/guides/parser_development.md for patterns
• See internal/ast/ast.go comments for AST usage examples

Continuous Linting

• Run make lint after implementation
• Fix linting issues immediately
• Use make fmt for formatting issues
• Verify with make fmt-check

Progress Tracking

• TodoWrite shows real-time progress
• Sprint plan updated at each milestone
• CHANGELOG.md grows incrementally
• Git commits create audit trail

Implementation Status Tracking (M-TESTING Learning):

When creating stubs for progressive development, document them explicitly in milestone summaries:

## Implementation Status (Milestone X Complete)

✅ **Complete**: CLI parsing, file walking, reporter integration
⏳ **Stubbed**: Test execution (returns skip for now)
📋 **Next**: Wire up pipeline/eval integration (Day X+1)

**Stub Locations** (for handoff/continuation):
- cmd/ailang/test.go:127 (executeUnitTest) - Returns skip
- cmd/ailang/test.go:139 (executePropertyTest) - Returns skip

Why this matters:

• Clear handoff points between milestones
• No surprises about what's functional vs stubbed
• Easy to find what needs wiring in next milestone
• Validates progressive development strategy

Pause Points

• After each milestone completion
• When tests fail (fix before continuing)
• When linting fails (fix before continuing)
• When user requests "pause"
• When encountering unexpected issues

Error Handling

• If tests fail: Show output, ask how to fix, don't proceed
• If linting fails: Show output, ask how to fix, don't proceed
• If implementation unclear: Ask for clarification, don't guess
• If milestone takes much longer than estimated: Pause and reassess

Parser debugging (M-DX9, v0.3.21):

• Use DEBUG_PARSER=1 ailang run test.ail to trace token flow
• Use DEBUG_DELIMITERS=1 ailang run test.ail to trace delimiter matching (nested braces, match expressions)
• Enhanced error messages now show context depth and suggest DEBUG_DELIMITERS=1 for deep nesting
• Check docs/guides/parser_development.md for troubleshooting
• Common issues documented in CLAUDE.md "Parser Developer Experience Guide" section

Resources

Parser Development Tools (M-DX9)

For parser-related sprints, use these M-DX9 tools:

1. Comprehensive Guide: docs/guides/parser_development.md

   • Quick start with example (adding new expression type)
   • Token position convention (AT vs AFTER) - prevents 30% of bugs
   • Common AST types reference
   • Parser patterns (delimited lists, optional sections, precedence)
   • Test infrastructure guide
   • Debug tools reference
   • Common gotchas and troubleshooting

2. Test Helpers: internal/parser/test_helpers.go

   • 15 helper functions for cleaner parser tests
   • AssertNoErrors(t, p) - Check for parser errors
   • AssertLiteralInt/String/Bool/Float(t, expr, value) - Check literals
   • AssertIdentifier(t, expr, name) - Check identifiers
   • AssertFuncCall/List/ListLength(t, expr) - Check structures
   • AssertDeclCount/FuncDecl/TypeDecl(t, file, ...) - Check declarations
   • All helpers call t.Helper() for clean stack traces

3. Debug Tooling: internal/parser/debug.go, internal/parser/delimiter_trace.go

   • DEBUG_PARSER=1 environment variable for token flow tracing
   • Shows ENTER/EXIT with cur/peek tokens for parseExpression, parseType
   • Zero overhead when disabled
   • Example: DEBUG_PARSER=1 ailang run test.ail

   NEW v0.3.21: Delimiter Stack Tracer

   • DEBUG_DELIMITERS=1 environment variable for delimiter matching tracing
   • Shows opening/closing of { } with context (match, block, case, function)
   • Visual indentation shows nesting depth
   • Detects delimiter mismatches and shows expected vs actual
   • Shows stack state on errors
   • Example: DEBUG_DELIMITERS=1 ailang run test.ail
   • Use when: Debugging nested match expressions, finding unmatched braces, understanding complex nesting

4. Enhanced Error Messages (v0.3.21): internal/parser/parser_error.go

When to use these tools:

• ✅ Any sprint touching internal/parser/ code
• ✅ Any sprint adding new expression/statement/type syntax
• ✅ Any sprint modifying AST nodes
• ✅ When encountering token position bugs
• ✅ When writing parser tests

Impact: M-DX9 tools reduce parser development time by 30% by eliminating token position debugging overhead.

Pattern Matching Pipeline (M-DX10)

For pattern matching sprints (adding/fixing patterns), understand the 4-layer pipeline:

Pattern changes propagate through parser → elaborator → type checker → evaluator. Each layer transforms the pattern representation.

The 4-Layer Pipeline

1. Parser (internal/parser/parser_pattern.go)

• Input: Source syntax (e.g., ::(x, rest), (a, b), [])
• Output: AST pattern nodes (ast.ConstructorPattern, ast.TuplePattern, ast.ListPattern)
• Role: Recognize pattern syntax and build AST
• Example: ::(x, rest) → ast.ConstructorPattern{Name: "::", Patterns: [x, rest]}

2. Elaborator (internal/elaborate/patterns.go)

• Input: AST patterns
• Output: Core patterns (core.ConstructorPattern, core.TuplePattern, core.ListPattern)
• Role: Convert surface syntax to core representation
• ⚠️ Special cases: Some AST patterns transform differently in Core!
  • :: ConstructorPattern → ListPattern{Elements: [head], Tail: tail} (M-DX10)
  • Why: Lists are ListValue at runtime, not TaggedValue with constructors

3. Type Checker (internal/types/patterns.go)

• Input: Core patterns
• Output: Pattern types, exhaustiveness checking
• Role: Infer pattern types, check coverage
• Example: ::(x: int, rest: List[int]) → List[int]

4. Evaluator (internal/eval/eval_patterns.go)

• Input: Core patterns + runtime values
• Output: Pattern match success/failure + bindings
• Role: Runtime pattern matching against values
• ⚠️ CRITICAL: Pattern type must match Value type!
  • ListPattern matches ListValue
  • ConstructorPattern matches TaggedValue
  • TuplePattern matches TupleValue
  • Mismatch = pattern never matches!

Cross-References in Code

Each layer has comments pointing to the next layer:

// internal/parser/parser_pattern.go
case lexer.DCOLON:
    // Parses :: pattern syntax
    // See internal/elaborate/patterns.go for elaboration to Core

// internal/elaborate/patterns.go
case *ast.ConstructorPattern:
    if p.Name == "::" {
        // Special case: :: elaborates to ListPattern
        // See internal/eval/eval_patterns.go for runtime matching
    }

// internal/eval/eval_patterns.go
case *core.ListPattern:
    // Matches against ListValue at runtime
    // If pattern type doesn't match value type, match fails

Common Pattern Gotchas

1. Two-Phase Fix Required (M-DX10 Lesson)

• Symptom: Parser accepts pattern, but runtime never matches
• Cause: Parser fix alone isn't enough - elaborator also needs fixing
• Solution: Check elaborator transforms pattern correctly for runtime
• Example: :: parsed as ConstructorPattern, but must elaborate to ListPattern

2. Pattern Type Mismatch

• Symptom: Pattern looks correct but never matches any value
• Cause: Pattern type doesn't match value type in evaluator
• Debug: Check matchPattern() in eval_patterns.go - does pattern type match value type?

3. Special Syntax Requires Special Elaboration

• Symptom: Standard elaboration doesn't work for custom syntax
• Solution: Add special case in elaborator (like :: → ListPattern)
• When: Syntax sugar, built-in constructors, or ML-style patterns

When to Use This Guide

Use when:

• ✅ Adding new pattern syntax (e.g., ::, @, guards)
• ✅ Fixing pattern matching bugs
• ✅ Understanding why patterns don't match at runtime
• ✅ Debugging elaboration or evaluation of patterns

Quick checklist for pattern changes:

1. Parser: Does parsePattern() recognize the syntax?
2. Elaborator: Does it transform to correct Core pattern type?
3. Type Checker: Does pattern type inference work?
4. Evaluator: Does pattern type match value type at runtime?

Impact: Understanding this pipeline prevents two-phase fix discoveries and reduces pattern debugging time by 50%.

Common API Patterns (M-TESTING Learnings)

⚠️ ALWAYS check make doc PKG=<package> before grepping or guessing APIs!

Quick API Lookup

# Find constructor signatures
make doc PKG=internal/testing | grep "NewCollector"
# Output: func NewCollector(modulePath string) *Collector

# Find struct fields
make doc PKG=internal/ast | grep -A 20 "type FuncDecl"
# Shows: Tests []*TestCase, Properties []*Property

Common Constructors

Package	Constructor	Signature	Notes
internal/testing	NewCollector(path)	Takes module path	M-TESTING
internal/elaborate	NewElaborator()	No arguments	Surface → Core
internal/types	NewTypeChecker(core, imports)	Takes Core prog + imports	Type inference
internal/link	NewLinker()	No arguments	Dictionary linking
internal/parser	New(lexer)	Takes lexer instance	Parser
internal/eval	NewEvaluator(ctx)	Takes EffContext	Core evaluator

Common API Mistakes

Test Collection (M-TESTING):

// ✅ CORRECT
collector := testing.NewCollector("module/path")
suite := collector.Collect(file)
for _, test := range suite.Tests { ... }  // Tests is the slice!

// ❌ WRONG
collector := testing.NewCollector(file, modulePath)  // Wrong arg order!
for _, test := range suite.Tests.Cases { ... }      // No .Cases field!

String Formatting:

// ✅ CORRECT
name := fmt.Sprintf("test_%d", i+1)

// ❌ WRONG - Produces "\x01" not "1"!
name := "test_" + string(rune(i+1))  // BUG!

Field Access:

// ✅ CORRECT
funcDecl.Tests        // []*ast.TestCase
funcDecl.Properties   // []*ast.Property

// ❌ WRONG
funcDecl.InlineTests  // Doesn't exist! Use .Tests

API Discovery Workflow

1. make doc PKG=<package> (~30 sec) ← Start here!
2. Check source file if you know location (grep "^func New" file.go)
3. Check test files for usage examples (grep "NewCollector" *_test.go)
4. Read docs/guides/ for complex workflows

Time savings: 80% reduction (5-10 min → 30 sec per lookup)

Full reference: See CLAUDE.md "Common API Patterns" section

DX Quick Reference

See resources/dx_quick_reference.md for quick reference card on DX improvements. Use during sprint execution to:

• Quickly decide whether to implement a DX improvement (decision matrix)
• Identify common DX patterns and their fixes
• Calculate ROI for improvements
• Use reflection questions after each milestone
• Apply documentation templates

Developer Tools Reference

See resources/developer_tools.md for comprehensive reference of all available make targets, ailang commands, scripts, and workflows. Load this when you need to:

• Know which test targets to use
• Update golden files after parser changes
• Verify stdlib changes
• Run evals or compare baselines
• Troubleshoot build/test/lint issues
• Find the right tool for any development task

Milestone Checklist

See resources/milestone_checklist.md for complete step-by-step checklist per milestone.

Prerequisites

• Working directory should be clean (or have only sprint-related changes)
• Current branch should be dev (or specified in sprint plan)
• All existing tests must pass before starting
• All existing linting must pass before starting
• Sprint plan must be approved and documented

Failure Recovery

If Tests Fail During Sprint

1. Show test failure output
2. Ask user: "Tests failing. Options: (a) fix now, (b) revert change, (c) pause sprint"
3. Don't proceed until tests pass

If Linting Fails During Sprint

1. Show linting output
2. Try auto-fix: make fmt
3. If still failing, ask user for guidance
4. Don't proceed until linting passes

If Implementation Blocked

1. Show what's blocking progress
2. Ask user for guidance or clarification
3. Consider simplifying the approach
4. Document the blocker in sprint plan

If Velocity Much Lower Than Expected

1. Pause and reassess after 2-3 milestones
2. Calculate actual velocity
3. Propose: (a) continue as-is, (b) reduce scope, (c) extend timeline
4. Update sprint plan with revised estimates

Progressive Disclosure

This skill loads information progressively:

1. Always loaded: This SKILL.md file (YAML frontmatter + execution workflow)
2. Execute as needed: Scripts in scripts/ directory (validation, checkpoints)
3. Load on demand: resources/milestone_checklist.md (detailed checklist)

Scripts execute without loading into context window, saving tokens while ensuring quality.

Notes

• This skill is long-running - expect it to take hours or days
• Pause points are built in - you're not locked into finishing
• Sprint plan is the source of truth - but reality may require adjustments
• Git commits create a reversible audit trail
• TodoWrite provides real-time visibility into progress
• Test-driven development is non-negotiable - tests must pass