Subsection Implementation Workflow

This skill provides a complete, automated workflow for implementing a single subsection from docs/implementation-plan.md. It orchestrates all project skills to ensure consistent, high-quality implementation.

Quick Start

To implement a subsection (e.g., 5.1.1):

/subsection-implementation 5.1.1

This will execute the entire workflow automatically.

Complete Workflow

Step 0: Clear Context (Fresh Start)

Goal: Start with a clean slate to avoid context pollution and ensure focused implementation.

Actions:

• Summarize current conversation state if needed
• Clear conversation history
• Focus only on the subsection to implement
• Load only relevant documentation and code

Why: Long conversations accumulate context that may interfere with focused implementation. Starting fresh ensures clarity.

---

Step 1: Read Subsection Requirements

Goal: Understand what needs to be implemented.

Actions:

1. Read docs/implementation-plan.md for the specified subsection
2. Extract:
   • Subsection title and description
   • Implementation notes
   • Files to create/modify
   • Subsection tests (acceptance criteria)
   • Spec references
3. Identify dependencies on previous subsections
4. Verify prerequisites are complete

Output: Clear understanding of requirements and test expectations.

---

Step 2: Create Implementation Plan

Goal: Break down the subsection into actionable tasks.

Actions:

1. Use TaskCreate to track implementation tasks:

   - Read and understand requirements
   - Implement code changes
   - Write subsection tests
   - Run quality checks
   - Update documentation
   - Commit and push
   

2. Mark tasks as in_progress when starting
3. Mark tasks as completed when done

Pattern: Follow @skills/phase-implementation/SKILL.md workflow

---

Step 3: Implement Code

Goal: Write production code following project patterns.

Actions:

1. Create/modify files as specified in subsection
2. Follow project conventions:
   • Type hints on all functions
   • Docstrings (Google style)
   • Error handling with custom error codes (see @skills/error-handling/SKILL.md)
   • API endpoints follow pattern (see @skills/api-endpoint-implementation/SKILL.md)
3. Import required dependencies
4. Handle edge cases
5. Add logging where appropriate

Patterns:

• Domain models: Use Pydantic v2
• Services: Return Result[T] types with error codes
• API endpoints: Use FastAPI with proper status codes
• Error handling: Follow @skills/error-handling/SKILL.md

Update task: Mark "Implement code changes" as completed

---

Step 4: Write Tests

Goal: Verify implementation meets all subsection test requirements.

Actions:

1. Read subsection tests from implementation plan
2. Write tests following @skills/test-writing/SKILL.md:
   • Test file: tests/unit/<module>/test_<component>.py
   • Test class: class Test<ComponentName>
   • Test method format: def test_subsection_X_Y_Z_requirement(self) -> None:
   • Include type annotations: -> None
3. Cover all subsection test cases listed in plan
4. Test success paths and error cases
5. Use descriptive test names
6. Follow Arrange-Act-Assert pattern

Example:

def test_subsection_5_1_1_calls_llm_when_enabled(self) -> None:
    """Test subsection 5.1.1: Scout calls LLM when enabled."""
    # Arrange
    scout = ScoutAgent(llm_enabled=True)
    game_state = create_test_game_state()

    # Act
    result = scout.analyze(game_state)

    # Assert
    assert result.success is True
    assert result.data.llm_used is True

Update task: Mark "Write subsection tests" as completed

---

Step 5: Run Quality Checks

Goal: Ensure code meets all quality standards before committing.

Actions:

1. Run linters:

   ruff check src/ tests/
   black --check src/ tests/
   

2. Run type checker:

   mypy --strict --explicit-package-bases src/
   

3. Run tests:

   pytest tests/ -v
   

4. Check coverage (if applicable):

   pytest tests/ --cov=src --cov-report=term-missing
   

CRITICAL: All checks must pass before proceeding. If any fail:

• Fix the issues immediately
• Re-run all checks
• Do not proceed until everything is green ✅

Pattern: Follow @skills/pre-commit-validation/SKILL.md

Update task: Mark "Run quality checks" as completed

---

Step 6: Update Documentation

Goal: Mark subsection as complete and document implementation.

Actions:

1. Update docs/implementation-plan.md:
   • Add ✅ to subsection title
   • Add Implementation Notes section with key details:

     **Implementation Notes:**
     - [Key implementation detail 1]
     - [Key implementation detail 2]
     - [Any deviations from plan]
     

   • Add Subsection Tests section with ✅:

     **Subsection Tests** ✅:
     - ✅ [Test 1 description]
     - ✅ [Test 2 description]
     

   • Add Test Coverage section:

     **Test Coverage** ✅:
     - **Subsection Tests**: ✅ X tests implemented and passing
     - **Test File**: ✅ `tests/unit/<module>/test_<component>.py`
     

2. Update any related documentation (API docs, architecture docs, etc.)

Update task: Mark "Update documentation" as completed

---

Step 7: Commit and Push

Goal: Save work with a clear, descriptive commit message.

Actions:

1. Stage all changes:

   git add <files>
   

2. Create commit following @skills/commit-format/SKILL.md:

   <type>(<scope>): <Subsection X.Y.Z> - <description>
   
   - [Implementation detail 1]
   - [Implementation detail 2]
   
   Tests:
   - [List of subsection tests added]
   
   Files:
   - <file1>: <description>
   - <file2>: <description>
   

3. Common commit types:
   • feat: New feature/functionality
   • fix: Bug fix
   • test: Test-only changes
   • refactor: Code restructuring
   • docs: Documentation only

Example:

feat(agents): Subsection 5.1.1 - Scout LLM enhancement

- Integrate Pydantic AI for board analysis
- Add LLM fallback to rule-based logic
- Implement retry mechanism (3 attempts with exponential backoff)
- Add LLM call metadata logging

Tests:
- ✅ 8 subsection tests covering LLM integration
- ✅ Test LLM calls, fallback, retries, and logging

Files:
- src/agents/scout.py: Add LLM integration with fallback
- tests/unit/agents/test_scout_llm.py: Add subsection tests
- docs/implementation-plan.md: Mark 5.1.1 as complete

4. Push to remote:

   git push origin main
   

CRITICAL: Only commit after:

• ✅ All tests pass
• ✅ All linters pass
• ✅ Type checker passes
• ✅ Documentation updated
• ✅ Implementation verified to work

Update task: Mark "Commit and push" as completed

---

Workflow Summary

1. Clear Context       → Start fresh
2. Read Requirements   → Understand subsection
3. Create Plan         → Track with TaskCreate
4. Implement Code      → Follow project patterns
5. Write Tests         → Verify requirements
6. Run Quality Checks  → Ensure standards (MUST PASS)
7. Update Docs         → Mark complete with notes
8. Commit & Push       → Save work with clear message

Subsection Format

Subsections are identified by their numbering in the implementation plan:

• Phase.Section.Subsection: e.g., 5.1.1, 5.2.3, 6.0.1
• Title: Descriptive name (e.g., "Scout LLM Enhancement")
• Tests: Listed as "Subsection Tests" in the plan
• Implementation Notes: Key details about implementation

Quality Gates

Before committing, all of these MUST be ✅:

1. ✅ All subsection tests pass
2. ✅ All existing tests still pass (no regressions)
3. ✅ Linters pass (ruff, black)
4. ✅ Type checker passes (mypy --strict)
5. ✅ Documentation updated with ✅ markers
6. ✅ Implementation notes added to plan
7. ✅ Commit message follows format

If any quality gate fails: Fix issues and re-validate. Do not proceed.

Best Practices

1. One subsection at a time: Never implement multiple subsections in one session
2. Clear context first: Always start fresh to avoid confusion
3. Follow the plan: Implement exactly what's specified in the subsection
4. Test thoroughly: Cover all listed subsection tests
5. Document clearly: Add implementation notes explaining key decisions
6. Verify before commit: Run all quality checks and ensure they pass
7. Commit atomically: One subsection = one commit
8. Push immediately: Share work with team right away

Common Edge Cases

When Subsection Tests Fail

1. Review test expectations in implementation plan
2. Debug implementation vs. requirements
3. Fix code or update requirements (if plan was wrong)
4. Document any deviations in Implementation Notes
5. Re-run all tests
6. Only proceed when all tests pass

When Implementation Differs from Plan

1. Update the implementation plan to match reality
2. Document why the change was necessary in Implementation Notes
3. Ensure subsection tests still cover the requirements
4. Verify acceptance criteria are still met

When Tests Reveal Design Issues

1. Fix the design issue first
2. Update implementation plan if requirements change
3. Update tests to match new design
4. Document lessons learned in Implementation Notes

When Prerequisites Are Missing

1. Stop immediately
2. Identify which previous subsections must be completed first
3. Implement prerequisites in order
4. Return to original subsection after prerequisites are done

Skills Integration

This skill orchestrates these existing skills:

• @skills/phase-implementation/SKILL.md: Overall implementation workflow
• @skills/test-writing/SKILL.md: Test patterns and conventions
• @skills/commit-format/SKILL.md: Commit message format
• @skills/error-handling/SKILL.md: Error handling patterns
• @skills/api-endpoint-implementation/SKILL.md: API endpoint patterns
• @skills/pre-commit-validation/SKILL.md: Quality checks before commit

Follow all patterns from these skills during implementation.

Example: Complete Workflow for Subsection 5.1.1

User: /subsection-implementation 5.1.1

AI Response:

Step 0: Clear Context

"Starting fresh implementation of subsection 5.1.1..."

Step 1: Read Requirements

"Reading docs/implementation-plan.md section 5.1.1..."

• Title: Scout LLM Enhancement
• Files: src/agents/scout.py
• Tests: 8 subsection tests listed

Step 2: Create Plan

"Creating task list..." [Creates TaskCreate with 6 tasks]

Step 3: Implement Code

"Implementing Scout LLM enhancement..." [Modifies src/agents/scout.py with LLM integration]

Step 4: Write Tests

"Writing subsection tests..." [Creates tests/unit/agents/test_scout_llm.py with 8 tests]

Step 5: Run Quality Checks

ruff check src/ tests/          # ✅ Pass
black --check src/ tests/       # ✅ Pass
mypy --strict src/              # ✅ Pass
pytest tests/ -v                # ✅ 8/8 passed

Step 6: Update Documentation

[Updates docs/implementation-plan.md]:

• Adds ✅ to subsection 5.1.1
• Adds Implementation Notes
• Marks Subsection Tests as ✅

Step 7: Commit & Push

git add src/agents/scout.py tests/unit/agents/test_scout_llm.py docs/implementation-plan.md
git commit -m "feat(agents): Subsection 5.1.1 - Scout LLM enhancement

- Integrate Pydantic AI for board analysis
- Add LLM fallback to rule-based logic
- Implement retry mechanism (3 attempts)
- Add LLM call metadata logging

Tests:
- ✅ 8 subsection tests covering LLM integration

Files:
- src/agents/scout.py: Add LLM integration with fallback
- tests/unit/agents/test_scout_llm.py: Add subsection tests
- docs/implementation-plan.md: Mark 5.1.1 as complete"

git push origin main

✅ Subsection 5.1.1 Complete!

---

Usage

Basic Usage

Implement a specific subsection:

/subsection-implementation 5.1.1

Advanced Usage

With specific branch:

/subsection-implementation 5.1.1 --branch feature/scout-llm

With dry-run (show plan without executing):

/subsection-implementation 5.1.1 --dry-run

Troubleshooting

"Subsection not found"

• Check that subsection exists in docs/implementation-plan.md
• Ensure proper format (e.g., 5.1.1, not 5-1-1)

"Prerequisites not complete"

• Check that previous subsections are marked ✅
• Implement prerequisites first

"Tests failing"

• Review subsection test requirements in plan
• Debug implementation vs. requirements
• Fix issues before proceeding

"Quality checks failing"

• Run checks individually to identify issue
• Fix linting/type errors
• Re-run until all checks pass