session-template

Session Template Applier

⚠️ MANDATORY: Read Project Documentation First

BEFORE applying session templates, you MUST read and understand the following project documentation:

Core Project Documentation

1. README.md - Project overview, features, and getting started
2. AI_DOCS/project-context.md - Tech stack, architecture, development workflow
3. AI_DOCS/code-conventions.md - Code style, formatting, best practices
4. AI_DOCS/tdd-workflow.md - TDD process, testing standards, coverage requirements

Session Context (if available)

1. .ai-context/ACTIVE_TASKS.md - Current tasks and priorities
2. .ai-context/CONVENTIONS.md - Project-specific conventions
3. .ai-context/RECENT_DECISIONS.md - Recent architectural decisions
4. .ai-context/LAST_SESSION_SUMMARY.md - Previous session summary

Additional AI Documentation

1. AI_DOCS/ai-tools.md - Session management workflow (CRITICAL for this skill)
2. AI_DOCS/ai-skills.md - Other specialized skills/agents available

Why This Matters

• Workflow Integration: Understand how ai-update-plan fits into session management
• Template Selection: Choose appropriate template based on project patterns
• Customization: Adapt templates to match project-specific requirements
• Task Context: Consider active tasks and recent decisions when planning

After reading these files, proceed with your template application task below.

Overview

Automatically apply task-specific planning templates to AI sessions, customizing generic steps with task-specific details.

When to Use

• Starting a new AI session with ai-start-task
• Need structured plan for common task types
• Want to ensure all important steps are included
• Standardizing workflow across team
• Complex tasks needing comprehensive planning

Available Templates

1. Feature Development (feature)

For adding new functionality

2. Bug Fix (bugfix)

For fixing existing issues

3. Refactoring (refactor)

For code improvement without behavior changes

4. Documentation (documentation)

For doc updates and improvements

5. Security Fix (security)

For security vulnerabilities and hardening

Usage Examples

Apply Template at Session Start

# Start session with feature template
apply feature development template for "Add OAuth2 authentication"

Output: Creates session with:

• Research & design phase
• TDD test-writing phase
• Implementation phase
• Security review phase
• Documentation phase

Apply Template to Existing Session

# Mid-session, realize you need structured plan
apply refactoring template for current session

Custom Template Selection

# Let skill analyze task and choose template
suggest template for "Fix memory leak in data processor"
# → Skill suggests: "bugfix" template

Template Structures

Feature Template

File: templates/feature.md

### Phase 1: Research & Design
- [ ] Review related code in the codebase
- [ ] Identify integration points
- [ ] Design data models and interfaces
- [ ] Document API contracts
- [ ] Consider edge cases and error scenarios

### Phase 2: Write Tests (TDD)
- [ ] Write tests for happy path scenarios
- [ ] Write tests for edge cases
- [ ] Write tests for error handling
- [ ] Write integration tests
- [ ] Ensure tests fail initially (red phase)

### Phase 3: Implementation
- [ ] Implement core functionality
- [ ] Add error handling
- [ ] Add input validation
- [ ] Add logging
- [ ] Run tests - should pass (green phase)

### Phase 4: Refactoring
- [ ] Remove duplication (DRY)
- [ ] Simplify complex logic
- [ ] Improve naming
- [ ] Add type hints where missing
- [ ] Keep tests passing

### Phase 5: Quality Check
- [ ] Run make check (format, lint, test, security)
- [ ] Fix all quality issues
- [ ] Verify coverage ≥ 80%
- [ ] Review with tdd-reviewer agent
- [ ] Apply quality-fixer for auto-fixable issues

### Phase 6: Documentation
- [ ] Update README if user-facing changes
- [ ] Add/update docstrings
- [ ] Update API documentation
- [ ] Add usage examples
- [ ] Document configuration changes

### Phase 7: Final Review
- [ ] Review all changes with git diff
- [ ] Test manually in development
- [ ] Verify all edge cases work
- [ ] Check performance implications
- [ ] Ready for PR/commit

Bugfix Template

File: templates/bugfix.md

### Phase 1: Reproduction
- [ ] Reproduce the bug reliably
- [ ] Document steps to reproduce
- [ ] Identify affected components
- [ ] Check if regression (previously working)
- [ ] Review related issues

### Phase 2: Root Cause Analysis
- [ ] Add debug logging
- [ ] Trace execution flow
- [ ] Identify exact failure point
- [ ] Understand why it fails
- [ ] Document root cause

### Phase 3: Write Reproduction Test (TDD)
- [ ] Write test that reproduces the bug
- [ ] Verify test fails (confirms bug exists)
- [ ] Test should be specific to the bug
- [ ] Include edge cases related to bug
- [ ] Document expected vs actual behavior

### Phase 4: Fix Implementation
- [ ] Implement minimal fix for root cause
- [ ] Avoid over-engineering the fix
- [ ] Add defensive checks if needed
- [ ] Add logging for future debugging
- [ ] Verify test now passes

### Phase 5: Regression Prevention
- [ ] Add tests for related scenarios
- [ ] Check if bug exists elsewhere
- [ ] Add validation to prevent recurrence
- [ ] Update error messages if applicable
- [ ] Document why bug occurred

### Phase 6: Quality & Testing
- [ ] Run full test suite (no regressions)
- [ ] Run make check
- [ ] Verify coverage maintained/improved
- [ ] Test manually with original report steps
- [ ] Check performance not degraded

### Phase 7: Documentation
- [ ] Update changelog
- [ ] Document fix in commit message
- [ ] Add code comments explaining fix
- [ ] Update docs if behavior changed
- [ ] Reference issue number if applicable

Refactoring Template

File: templates/refactor.md

### Phase 1: Establish Safety Net
- [ ] Ensure tests exist for code being refactored
- [ ] Run tests - all must pass (baseline)
- [ ] Run make check - must pass
- [ ] Commit current state (safety checkpoint)
- [ ] Document current behavior

### Phase 2: Identify Improvements
- [ ] Identify code smells (duplication, complexity)
- [ ] Find violations of SOLID principles
- [ ] Look for unclear naming
- [ ] Identify missing abstractions
- [ ] List specific improvements needed

### Phase 3: Plan Refactoring Steps
- [ ] Break into small, safe steps
- [ ] Prioritize by risk/impact
- [ ] Identify dependencies between steps
- [ ] Plan to keep tests green throughout
- [ ] Consider breaking into multiple commits

### Phase 4: Refactor Incrementally
- [ ] Make one small change at a time
- [ ] Run tests after each change
- [ ] Keep tests passing (always green)
- [ ] Commit after each successful step
- [ ] If tests fail, revert and adjust approach

### Phase 5: Improve Design
- [ ] Extract methods/functions
- [ ] Remove duplication (DRY)
- [ ] Improve naming (clarity)
- [ ] Simplify complex conditionals
- [ ] Add type hints for clarity

### Phase 6: Quality Verification
- [ ] Run make check (must pass)
- [ ] Verify no behavior changes
- [ ] Check performance not degraded
- [ ] Review with tdd-reviewer agent
- [ ] Ensure coverage maintained

### Phase 7: Documentation
- [ ] Update docstrings for changed interfaces
- [ ] Add comments for complex logic
- [ ] Document why refactoring was needed
- [ ] Update architecture docs if applicable
- [ ] Record design decisions

Documentation Template

File: templates/documentation.md

### Phase 1: Content Audit
- [ ] Review existing documentation
- [ ] Identify outdated content
- [ ] Find missing documentation
- [ ] Check for broken links
- [ ] Review user feedback/questions

### Phase 2: Content Planning
- [ ] Define documentation scope
- [ ] Identify target audience
- [ ] Plan docume