Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
375 changes: 1 addition & 374 deletions .github/prompts/workstream-execution.prompt.md
Original file line number Diff line number Diff line change
Expand Up @@ -1373,380 +1373,7 @@ For everything else: **proceed with best effort and document assumptions**.

---

## �️ Proven Patterns for Complex Tasks (FerrisScript Learnings)

**When to Use These Patterns**: Multi-hour implementations (4+ hours), cross-crate changes, reflection/metadata systems, or features touching multiple pipeline stages.

### Pattern 1: Checkpoint Methodology ✅

**Source**: Phase 4.5 struct literal implementation (50% faster than Phase 4)

**Problem**: Large features are hard to pause/resume, risky to implement all-at-once

**Solution**: Break into 8 structured checkpoints with natural test/commit points

**Checkpoint Structure**:

1. **Checkpoint 1-2**: Foundation (AST nodes, basic parsing)
2. **Checkpoint 3-4**: Core logic (type checking, validation)
3. **Checkpoint 5-6**: Integration (runtime, conversions)
4. **Checkpoint 7**: Error handling + recovery
5. **Checkpoint 8**: Integration tests + documentation

**Benefits**:

- Natural pause points every 15-30 minutes
- Easy to resume work (clear next checkpoint)
- Early bug detection (test after each checkpoint)
- Clear progress tracking (8/8 checkpoints = done)

**Example Application** (Phase 4.5):

- Checkpoint 1: AST StructLiteral node
- Checkpoint 2: Parser basic syntax (`Type { }`)
- Checkpoint 3: Parser field parsing (`field: value`)
- Checkpoint 4: Type checker validate type name
- Checkpoint 5: Type checker validate fields
- Checkpoint 6: Runtime evaluate literal
- Checkpoint 7: Error recovery (missing fields)
- Checkpoint 8: Integration tests (all types)

**How to Apply**:

- For 4-6 hour feature: 8 checkpoints (~30 min each)
- For 10+ hour feature: 3 sub-phases × 8 checkpoints each (24 total)
- Test after each checkpoint (no commit until passing)
- Document checkpoint completion in execution plan

**Metrics**: 50% faster implementation, 3 bugs caught early (vs late-stage rework)

---

### Pattern 2: MVP + Robustness Split ✅

**Source**: Phase 4.5 robustness testing (39 tests added after MVP)

**Problem**: Trying to cover all edge cases during MVP slows progress

**Solution**: Separate MVP implementation from robustness testing

**MVP Phase** (Focus on happy path):

- Basic functionality working
- Core tests passing (feature works)
- Integration with existing systems

**Robustness Phase** (Focus on edge cases):

- Missing/wrong/extra data
- Type coercion and conversions
- Error recovery and diagnostics
- Integration examples
- Performance edge cases

**Benefits**:

- MVP completes faster (don't get stuck on edge cases)
- MVP proves feasibility early
- Robustness testing validates production-readiness
- Zero bugs found during robustness = good MVP quality

**Example Application** (Phase 4.5):

**MVP** (2.5 hours):

- Struct literal syntax working
- 31 tests re-enabled
- 548 tests passing

**Robustness** (3 hours):

- 27 compiler edge case tests
- 12 runtime execution tests
- 5 integration examples
- 587 tests passing (+39)

**How to Apply**:

- MVP first: Get feature working, basic tests passing
- Commit MVP: "feat: [Feature] MVP complete"
- Robustness next: Add edge case tests, examples
- Commit robustness: "feat: [Feature] complete - robustness testing"

**Metrics**: 0 bugs found during robustness testing (good MVP indicator)

---

### Pattern 3: Error Code Semantic Grouping ✅

**Source**: Phase 4.5 struct literal errors (E701-E710 range)

**Problem**: Large error code ranges (E100-E199) hard to navigate

**Solution**: Allocate semantic ranges for feature families

**Grouping Strategy**:

- E70x: Struct literal errors (all types)
- E801-E815: Export annotation errors (future)
- Semantic > unique codes per type

**Benefits**:

- Easy to find related errors (all struct errors start with E7)
- Can reuse codes across similar types (E701 = unknown field on ANY type)
- Clear documentation patterns (E70x documentation section)

**Example Application** (Phase 4.5):

- E701-E703: Unknown field (Color, Rect2, Transform2D)
- E704-E706: Missing field (reserved for future)
- E707-E710: Type mismatch (reserved for future)
- Reused E205 for Vector2 (existing error code)

**How to Apply**:

- Allocate 10-15 code range for feature
- Group by category (parser, type checker, runtime)
- Reuse codes across similar types
- Document range in ERROR_CODES.md

**Anti-Pattern**: E701 = Color field, E702 = Rect2 field → hard to remember

---

### Pattern 4: Integration Examples as Tests ✅

**Source**: Phase 4.5 integration examples (5 .ferris files)

**Problem**: Unit tests don't validate real-world usage patterns

**Solution**: Create example files demonstrating practical patterns

**Example File Structure**:

```rust
// examples/struct_literals_color.ferris
# TEST: Color RGBA manipulation
# CATEGORY: Type System
# DESCRIPTION: Demonstrates Color struct literals with integer coercion
# EXPECT: success

// Real-world code here
let red = Color { r: 1, g: 0, b: 0, a: 1 }; // Integer coercion
```

**Benefits**:

- Examples serve as documentation
- Examples validate real-world patterns
- Examples can be used in test harness (metadata protocol)
- Examples show best practices

**Example Application** (Phase 4.5):

- `struct_literals_color.ferris` - RGBA manipulation
- `struct_literals_vector2.ferris` - Vector math
- `struct_literals_rect2.ferris` - Boundaries
- `struct_literals_transform2d.ferris` - Transformations
- `struct_literals_functions.ferris` - Function patterns

**How to Apply**:

- Create 3-5 example files per feature
- Include TEST metadata for harness integration
- Demonstrate practical patterns (not just syntax)
- Add to examples/ directory

**Note**: Examples may not run through test harness immediately (Phase 5 work), but serve as reference

---

### Pattern 5: Sub-Phase Decomposition ✅

**Source**: Phase 5 execution plan (3 sub-phases for @export)

**Problem**: 20+ hour features too large for single-session implementation

**Solution**: Decompose into independent sub-phases

**Sub-Phase Structure**:

1. **Sub-Phase 1: Parser & AST** (4-6 hours)
- Lexer tokens
- Parser grammar extension
- AST node definitions
- 8 checkpoints

2. **Sub-Phase 2: Type Checker & Validation** (5-7 hours)
- Semantic validation
- Error code implementation
- Compatibility matrix
- 8 checkpoints

3. **Sub-Phase 3: Runtime & Integration** (9-13 hours)
- Metadata storage
- Cross-crate integration
- Godot binding
- 8 checkpoints

**Benefits**:

- Each sub-phase can be implemented in separate session
- Clear dependencies (must do Phase 1 before Phase 2)
- Natural commit points (commit after each sub-phase)
- Parallel work possible (if independent)

**Example Application** (Phase 5):

- Session 1: Parser + AST (4-6 hours)
- Session 2: Type Checker (5-7 hours)
- Session 3: Runtime + Godot (9-13 hours)
- Total: 18-26 hours across 3 sessions

**How to Apply**:

- For 10+ hour feature: Split into 3 sub-phases
- For 20+ hour feature: Split into 3-4 sub-phases
- Each sub-phase has 8 checkpoints
- Document sub-phase dependencies in execution plan

**Metrics**: Phase 5 estimate = 23-31 hours → 3 sub-phases × 8 checkpoints = 24 total

---

### Pattern 6: Test-First Checkpoint Validation ✅

**Source**: Phase 4.5 zero bugs during robustness testing

**Problem**: Late-stage bugs require rework and context switching

**Solution**: Write tests before implementation, validate at each checkpoint

**Test-First Workflow**:

1. Write test for checkpoint functionality
2. Run test (expect failure)
3. Implement checkpoint code
4. Run test (expect pass)
5. Move to next checkpoint

**Benefits**:

- Tests catch issues immediately
- Clear success criteria (test passes = checkpoint done)
- Zero bugs found during robustness = good quality
- Tests serve as specification

**Example Application** (Phase 4.5):

- Checkpoint 3: Type checker validate type name
- Test: `test_struct_literal_wrong_type_name()` (write first)
- Implement: Type name validation (implement second)
- Result: Test passes → checkpoint complete

**How to Apply**:

- Write test before each checkpoint
- Run test after implementation
- Don't move to next checkpoint until tests pass
- Document test count in checkpoint tracking

**Metrics**: 0 bugs found during robustness testing = MVP quality validated

---

### Pattern 7: Execution Plan Template ✅

**Source**: Phase 5 execution plan (comprehensive planning doc)

**Problem**: Ad-hoc planning leads to scope creep and missed requirements

**Solution**: Use structured execution plan template

**Required Sections**:

1. **Executive Summary** (goal, scope, why deferred if applicable)
2. **Effort Estimation** (breakdown by category, total hours)
3. **Sub-Phase Breakdown** (if 10+ hours)
4. **Checkpoint Tracking** (24 total for complex features)
5. **Testing Strategy** (MVP + robustness split)
6. **Error Code Definitions** (allocated range)
7. **File Modifications** (what will change)
8. **Success Criteria** (functional + quality + integration)
9. **Learnings from Previous Phases** (apply proven patterns)
10. **Implementation Notes** (technical approach)

**Benefits**:

- Complete planning before implementation
- Clear scope and requirements
- Effort estimation for scheduling
- Pattern reuse (apply Phase 4.5 learnings)

**Example Application** (Phase 5):

- 23-31 hour estimate (6 categories)
- 3 sub-phases (Parser, Type Checker, Runtime)
- 24 checkpoints (8 per sub-phase)
- 51 total tests (30 MVP + 21 robustness)
- Learnings from Phase 4.5 applied

**How to Apply**:

- Create execution plan before implementation
- Use PHASE_X_EXECUTION_PLAN.md template
- Document all decisions and assumptions
- Update plan during implementation

---

### When to Use These Patterns

**Use Checkpoint Methodology When**:

- Feature will take 4+ hours
- Multiple pipeline stages affected (parser + type checker + runtime)
- Easy to get lost in implementation details

**Use MVP + Robustness Split When**:

- Feature has many edge cases
- Want to prove feasibility quickly
- Risk of scope creep

**Use Sub-Phase Decomposition When**:

- Feature will take 10+ hours
- Can break into independent phases
- Want to implement across multiple sessions

**Use Test-First Validation When**:

- Feature has clear specifications
- Want to minimize bugs
- Need confidence in implementation quality

**Use All Patterns Together When**:

- Complex feature (20+ hours)
- Cross-crate changes
- Reflection/metadata systems
- High-risk implementation

**Example**: Phase 5 @export uses ALL patterns:

- ✅ Checkpoint methodology (24 checkpoints)
- ✅ MVP + robustness split (30 MVP + 21 robustness)
- ✅ Sub-phase decomposition (3 sub-phases)
- ✅ Error code grouping (E801-E815)
- ✅ Integration examples (3 files)
- ✅ Test-first validation (51 tests)
- ✅ Execution plan template (comprehensive doc)

---

## �🎭 Your Role & Expertise
## 🎭 Your Role & Expertise

You are a **senior software engineer** with:

Expand Down
1 change: 0 additions & 1 deletion .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,6 @@ node_modules/

# Temporary files (PR bodies, scripts)
/temp/
.github/PR_DESCRIPTION.md

# OS
Thumbs.db
Expand Down
Loading
Loading