Assumption Tracking

Assumption Tracking Skill

// Project Autopilot - Assumption Management // Copyright (c) 2026 Jeremy McSpadden jeremy@fluxlabs.net

Purpose: Explicitly track assumptions, define validation methods, and create failure plans to handle invalidated assumptions.

Why Assumptions Matter

Assumptions are beliefs about the project that haven't been verified:

• Valid assumptions enable confident planning
• Invalid assumptions cause cascading failures
• Untracked assumptions become silent risks

This skill ensures assumptions are:

1. Explicitly stated - No hidden assumptions
2. Categorized - Technical, business, or external
3. Validated - With clear criteria
4. Planned for failure - With mitigation and fallback

Assumption Categories

Technical Assumptions

Beliefs about technical capabilities:

• API availability and behavior
• Library/framework compatibility
• Performance characteristics
• Infrastructure capabilities
• Data format and structure

Business Assumptions

Beliefs about requirements and priorities:

• User behavior expectations
• Requirement interpretations
• Priority orderings
• Scope boundaries
• Timeline expectations

External Assumptions

Beliefs about external factors:

• Third-party service SLAs
• Integration partner readiness
• Timeline dependencies
• Resource availability
• Regulatory compliance

Assumption Template

YAML Format

assumptions:
  - id: A001
    statement: "Supabase rate limits won't affect normal usage"
    category: external
    criticality: high       # high | medium | low
    phase: 3               # Phase where assumption matters
    validation:
      method: "load_test"   # load_test | api_check | manual | code_review
      command: "npm run test:load"
      criteria: "< 10% failures at 100 concurrent users"
      when: "before_phase_3"  # when to validate
    failure_plan:
      impact: "Authentication delays during peak usage"
      mitigation: "Implement request queuing with exponential backoff"
      fallback: "Switch to self-hosted auth service"
      effort: "medium"      # low | medium | high
    status: untested        # untested | validated | invalidated
    validated_at: null
    notes: ""

  - id: A002
    statement: "Next.js 14 App Router supports all required features"
    category: technical
    criticality: medium
    phase: 1
    validation:
      method: "code_review"
      command: null
      criteria: "All planned features have documentation"
      when: "before_planning"
    failure_plan:
      impact: "May need to use Pages Router for some features"
      mitigation: "Identify feature gaps early, plan workarounds"
      fallback: "Fall back to Pages Router or hybrid approach"
      effort: "high"
    status: validated
    validated_at: "2026-01-29"
    notes: "Verified against Next.js 14 docs"

  - id: A003
    statement: "User data model matches existing schema"
    category: business
    criticality: high
    phase: 2
    validation:
      method: "api_check"
      command: "curl -X GET https://api.example.com/users/schema"
      criteria: "Schema includes: id, email, name, created_at"
      when: "before_phase_2"
    failure_plan:
      impact: "Database migration complexity increases"
      mitigation: "Add migration step to transform data"
      fallback: "Create new user entity, migrate data async"
      effort: "high"
    status: untested
    validated_at: null
    notes: ""

Markdown Format

## Assumptions

### Phase Assumptions
| ID | Assumption | Category | Criticality | Status |
|----|------------|----------|-------------|--------|
| A001 | Supabase rate limits won't affect normal usage | external | High | Untested |
| A002 | Next.js 14 App Router supports all required features | technical | Medium | Validated |
| A003 | User data model matches existing schema | business | High | Untested |

### Validation Tasks
| Assumption | Method | When | Criteria |
|------------|--------|------|----------|
| A001 | load_test | Before Phase 3 | < 10% failures at 100 users |
| A002 | code_review | Before planning | All features documented |
| A003 | api_check | Before Phase 2 | Schema includes required fields |

### Failure Plans
| Assumption | If Fails | Mitigation | Fallback |
|------------|----------|------------|----------|
| A001 | Auth delays | Request queuing | Self-hosted auth |
| A002 | Feature gaps | Plan workarounds | Pages Router hybrid |
| A003 | Schema mismatch | Migration step | New entity + async migrate |

Validation Protocol

Validation Methods

FUNCTION validateAssumption(assumption):
    result = {
        assumption_id: assumption.id,
        passed: false,
        evidence: null,
        error: null,
        validated_at: null
    }

    SWITCH assumption.validation.method:
        CASE "load_test":
            # Run load test
            output = runCommand(assumption.validation.command)
            result.passed = evaluateCriteria(output, assumption.validation.criteria)
            result.evidence = {
                type: "load_test",
                output: output,
                metrics: parseLoadTestMetrics(output)
            }

        CASE "api_check":
            # Check API endpoint
            IF assumption.validation.command:
                output = runCommand(assumption.validation.command)
            ELSE:
                output = fetchAPI(assumption.validation.endpoint)
            result.passed = evaluateCriteria(output, assumption.validation.criteria)
            result.evidence = {
                type: "api_check",
                response: output
            }

        CASE "manual":
            # Request manual verification
            LOG "Manual verification required for: {assumption.statement}"
            user_response = requestManualVerification(assumption)
            result.passed = user_response.confirmed
            result.evidence = {
                type: "manual",
                verified_by: user_response.user,
                notes: user_response.notes
            }

        CASE "code_review":
            # Analyze code or documentation
            LOG "Code review required for: {assumption.statement}"
            review_result = performCodeReview(assumption.validation.criteria)
            result.passed = review_result.meets_criteria
            result.evidence = {
                type: "code_review",
                findings: review_result.findings
            }

    IF result.passed:
        assumption.status = "validated"
        assumption.validated_at = now()
        LOG "✅ Assumption {assumption.id} VALIDATED"
    ELSE:
        assumption.status = "invalidated"
        LOG "❌ Assumption {assumption.id} INVALIDATED"
        activateFailurePlan(assumption.failure_plan)

    RETURN result

Automatic Validation Triggers

validation_triggers:
  - when: "before_planning"
    validate:
      - assumptions WHERE criticality == "high" AND phase == null

  - when: "before_phase"
    validate:
      - assumptions WHERE phase == current_phase AND status == "untested"

  - when: "phase_complete"
    validate:
      - assumptions WHERE phase == current_phase AND status == "untested"

  - when: "on_demand"
    validate:
      - assumption specified by user

Failure Plan Activation

When Assumption Invalidated

FUNCTION activateFailurePlan(failure_plan):
    LOG "⚠️ Activating failure plan"
    LOG "Impact: {failure_plan.impact}"
    LOG "Mitigation: {failure_plan.mitigation}"

    # Create mitigation task
    task = {
        type: "assumption_failure",
        title: "Mitigate invalidated assumption",
        description: failure_plan.mitigation,
        priority: "high",
        effort: failure_plan.effort,
        blocks: getAffectedPhases(assumption)
    }

    addTask(task)

    # If mitigation fails, fallback
    IF mitigationFails():
        LOG "⚠️ Mitigation failed, activating fallback"
        LOG "Fallback: {failure_plan.fallback}"

        fallback_task = {
            type: "assumption_fallback",
            title: "Implement fallback for assumption failure",
            description: failure_plan.fallback,
            priority: "critical"
        }

        addTask(fallback_task)

Failure Plan Impact Assessment

FUNCTION assessFailurePlanImpact(assumption):
    impact = {
        affected_phases: [],
        affected_tasks: [],
        scope_change: false,
        timeline_impact: "unknown"
    }

    # Find affected phases
    FOR each phase IN project.phases:
        IF phase.depends_on_assumption(assumption.id):
            impact.affected_phases.add(phase.number)
            impact.affected_tasks.extend(phase.tasks)

    # Determine if scope change needed
    IF assumption.failure_plan.effort == "high":
        impact.scope_change = true
        impact.timeline_impact = "significant"
    ELSE IF assumption.failure_plan.effort == "medium":
        impact.timeline_impact = "moderate"
    ELSE:
        impact.timeline_impact = "minimal"

    RETURN impact

Assumption Tracking in Phases

Phase Template Addition

Add to each phase file:

## Assumptions

### Phase Assumptions
| ID | Assumption | Criticality | Status |
|----|------------|-------------|--------|
| A001 | {statement} | High | Untested |
| A002 | {statement} | Medium | Validated |

### Validation Schedule
| Assumption | Method | When | Criteria |
|------------|--------|------|----------|
| A001 | load_test | Before Phase 3 | < 10% failures |
| A002 | api_check | Phase start | Schema match |

### Failure Plans
| Assumption | If Fails | Mitigation | Fallback |
|------------|----------|------------|----------|
| A001 | Auth delays | Request queuing | Self-hosted |
| A002 | Schema mismatch | Migration step | New entity |

Assumption Status Tracking

# In phase file or .autopilot/assumptions.yaml
assumptions_status:
  - id: A001
    status: validated
    validated_at: "2026-01-29T10:30:00Z"
    evidence: "Load test passed with 3% failure rate"

  - id: A002
    status: invalidated
    validated_at: "2026-01-29T11:00:00Z"
    evidence: "Schema missing required fields"
    mitigation_status: in_progress

Integration Points

With /autopilot:plan

plan.md reads:
    - assumptions WHERE phase == current_phase
    - Creates validation tasks
    - Adds assumption checks to phase quality gate

With /autopilot:takeoff

build.md executes:
    - IF untested assumptions for current phase:
        FIRST validate assumptions
        IF any invalidated:
            Pause and show failure plan
            Wait for user decision

With /autopilot:scan

scan.md includes:
    - List all assumptions
    - Show validation status
    - Flag invalidated assumptions
    - Suggest validation schedule

With /autopilot:cockpit

resume.md loads:
    - Assumption status from previous session
    - Continues with validation state preserved

Commands

List Assumptions

/autopilot:assumptions list
/autopilot:assumptions list --phase=3
/autopilot:assumptions list --status=untested

Validate Assumption

/autopilot:assumptions validate A001
/autopilot:assumptions validate --phase=3
/autopilot:assumptions validate --all

Update Assumption Status

/autopilot:assumptions mark A001 --status=validated
/autopilot:assumptions mark A001 --status=invalidated

Output Format

Assumption Validation Report

## Assumption Validation Report

**Phase:** 3 - User Dashboard
**Validated:** 2026-01-29

### Summary
| Status | Count |
|--------|-------|
| Validated | 2 |
| Invalidated | 1 |
| Untested | 1 |

### Results

#### ✅ A001: Supabase rate limits
**Status:** Validated
**Method:** load_test
**Evidence:** 3% failure rate at 100 concurrent users (criteria: <10%)

#### ✅ A002: Next.js 14 features
**Status:** Validated
**Method:** code_review
**Evidence:** All required features documented

#### ❌ A003: User schema match
**Status:** Invalidated
**Method:** api_check
**Evidence:** Schema missing `avatar` field

**Failure Plan Activated:**
- Impact: Database migration complexity increases
- Mitigation: Add migration step to transform data
- Fallback: Create new user entity, migrate data async

#### ⏳ A004: Payment gateway latency
**Status:** Untested
**When:** Before Phase 5

Best Practices

Writing Good Assumptions

DO:

• Be specific and testable
• Include clear validation criteria
• Define realistic failure plans
• Categorize by type (technical, business, external)
• Assign criticality based on impact

DON'T:

• Leave assumptions implicit
• Assume without evidence
• Skip failure planning for critical assumptions
• Wait until failure to consider alternatives

Validation Timing

Failure Plan Quality

Good failure plans have:

• Clear impact description
• Specific mitigation steps
• Fallback option that doesn't require the assumption
• Effort estimate