# ⚙️ Objective Task Complexity Framework – Technical Specification {#spec-ROADCREW-001}

> This document defines **how** to implement the feature. All "what/why" lives in PRD.

## 1. Mapping: PRD → Spec

| PRD Requirement  | Satisfied In Spec Section |
| ---------------- | ------------------------ |
| R1: Objective dimension scoring | 4.1, 4.2 |
| R2: Maintain 1-10 classification | 4.3, 8.3 |
| R3: Multiple assignment options | 4.1.4, 8.6 |
| R4: Profile validation | 5.1, 8.5 |
| R5: Dimension guidance | 4.4, 8.4 |
| R6: Legacy mode support | 4.3, 8.2 |

## 2. Technical Requirements

### 2.1 Functional Requirements (max 6 bullets—must map PRD 1:1)
- Score tasks on four objective dimensions: determinism, context breadth, verification cost, domain knowledge
- Calculate 1-10 classification as derived output from task profile for backward compatibility
- Implement assignment recommendation function considering task profile and available resource capabilities
- Store actual completion metrics against profiles to enable calibration and learning
- Provide dimension assessment guidance with examples from completed tasks
- Support legacy single-score mode and new profile mode in parallel

### 2.2 Non-Functional Requirements (≤20 words each)
- **Performance:** Profile generation completes in under 1 second; assignment calculation under 100ms
- **Security:** Task profiles stored in YAML with no sensitive data exposure
- **Reliability:** Assignment function deterministic for same profile and resource inputs
- **Scalability:** Support 1000+ task profiles per repository with sub-second query performance

### 2.3 Out of Scope (3 bullets max, ≤12 words each)
- Real-time profile adjustment as tasks progress through development lifecycle
- Machine learning based profile generation from task description text
- External system integration for resource capacity or availability tracking

## 3. Design Overview (≤100 words)
Introduce TaskProfile as first-class object separate from worker assignment. Profile contains four objective dimension scores (1-10 each). Existing 1-10 classification becomes derived field calculated from profile using weighted formula. New assign() function takes TaskProfile + ResourcePool → AssignmentOptions[]. Resources defined by capability thresholds per dimension (e.g., AI handles determinism<4, verification<5). Existing classification-zones.js becomes compatibility layer. All current code continues working; new profile-aware code adds capabilities without breaking changes.

## 4. Architecture & Implementation

### 4.1 New/Modified Services (bullets, each ≤20 words)

#### 4.1.1 Task Profile Service
- **Module:** `scripts/utils/roadcrew/task-profile.ts` – Core TaskProfile class with dimension scoring and validation
- **Purpose:** Define objective task characteristics independent of worker assignment decisions

#### 4.1.2 Classification Bridge
- **Module:** `scripts/utils/roadcrew/classification-bridge.ts` – Bidirectional conversion between profiles and legacy 1-10 scores
- **Extends:** `classification-zones.js` – Add profileToClassification() and classificationToProfile() functions

#### 4.1.3 Resource Pool Manager
- **Module:** `scripts/utils/roadcrew/resource-pool.ts` – Defines AI and human capability boundaries per dimension
- **Purpose:** Model what each resource type can reliably handle

#### 4.1.4 Assignment Recommender
- **Module:** `scripts/utils/roadcrew/assignment-recommender.ts` – Generate assignment options from profile and resource pool
- **Purpose:** Replace current classification → assignment mapping with profile → options logic

### 4.2 Data Model Changes

#### TaskProfile Interface
```typescript
interface TaskProfile {
  // Objective dimensions (1-10 scale) — SOURCE OF TRUTH
  determinism: number;      // 1=mechanical, 10=creative judgment
  contextBreadth: number;   // 1=single file, 10=system-wide
  verificationCost: number; // 1=instant feedback, 10=production-only
  domainKnowledge: number;  // 1=generic, 10=specialized expertise
  
  // Derived fields (READ-ONLY, calculated from dimensions for backward compatibility)
  classification: number;   // 1-10 calculated from dimensions via weighted formula
  zone: ClassificationZone; // Derived from classification (references existing zones)
  
  // Metadata
  estimatedHours?: number;  // Optional effort estimate
  actualHours?: number;     // Recorded after completion
  calibrationDelta?: number;// Difference for learning
}
```

**IMPORTANT: Existing classification field becomes derived/read-only.** Dimensions are now the source of truth. See [classification-zones.ts](../../scripts/utils/roadcrew/classification-zones.ts) for current zone definitions (will be preserved).

#### ResourceCapability Interface
```typescript
interface ResourceCapability {
  name: string;              // e.g., "AI-Claude-Opus", "Junior-Engineer", "Senior-Engineer"
  type: 'ai' | 'human';
  maxDeterminism: number;    // Won't take tasks above this
  maxContext: number;
  maxVerification: number;
  maxDomain: number;
  costPerHour?: number;      // Optional for cost optimization
}
```

#### Configuration Extensions (assignment-rules.yml)

**NEW SECTION** to be added to [config/assignment-rules.yml](../../config/assignment-rules.yml) template:

```yaml
# NEW: Resource Capability Definitions (Phase 2)
# Defines what each resource type can reliably handle per dimension
resource_capabilities:
  ai_agents:
    claude_opus:
      max_determinism: 4  # Won't take above this on determinism dimension
      max_context: 6      # Limited codebase understanding
      max_verification: 5 # Can't handle production-only verification
      max_domain: 4       # Limited specialized domain knowledge
  
  human_resources:
    junior_engineer:
      max_determinism: 10  # Can handle any determinism level
      max_context: 6       # Limited codebase understanding (smaller PRs)
      max_verification: 7  # Some manual testing capability
      max_domain: 5        # Limited to common patterns
    
    senior_engineer:
      max_determinism: 10  # Can handle creative judgment
      max_context: 10      # Full system understanding
      max_verification: 10 # Can architect testing strategies
      max_domain: 10       # Deep specialized knowledge
```

**Backward Compatibility:** Existing single-score assignments (classification-1 through classification-10) remain in config and continue working via adapter layer (see Phase 0 and Section 4.5).

---

### 4.3 API Changes

#### NEW Functions (Phase 1-3)

| Method | Signature | Purpose | Status | File |
|--------|----------|---------|--------|------|
| createProfile | (dimensions: Partial<TaskProfile>) => TaskProfile | Generate profile from dimensions | **NEW** | `scripts/utils/roadcrew/task-profile.ts` (NEW) |
| profileToClassification | (profile: TaskProfile) => number | Derive 1-10 score | **NEW** | `scripts/utils/roadcrew/classification-bridge.ts` (NEW) |
| classificationToProfile | (classification: number) => TaskProfile | Convert legacy score | **NEW** | `scripts/utils/roadcrew/classification-bridge.ts` (NEW) |
| recommendAssignments | (profile: TaskProfile, pool: ResourceCapability[]) => AssignmentOption[] | Generate options | **NEW** | `scripts/utils/roadcrew/assignment-recommender.ts` (NEW) |
| validateProfile | (profile: TaskProfile) => ValidationResult | Check consistency | **NEW** | `scripts/utils/roadcrew/task-profile.ts` (NEW) |

#### EXISTING Functions (Preserved with Optional Extensions)

| Method | Current File | Change | Purpose | Backward Compat |
|--------|------|--------|---------|-----------------|
| getZoneForScore | [classification-zones.ts](../../scripts/utils/roadcrew/classification-zones.ts) | Add optional `profile?: TaskProfile` parameter | Use profile if available, fall back to classification | ✅ Fully compatible |
| determineAssigneeByClassification | [auto-fill.ts](../../scripts/utils/roadcrew/auto-fill.ts) | Add optional `profile?: TaskProfile` parameter | Accept TaskProfile for richer context; use legacy logic if not provided | ✅ Fully compatible |
| autoFillIssue | [auto-fill.ts](../../scripts/utils/roadcrew/auto-fill.ts) | Add optional `profile?: TaskProfile` parameter | Capture TaskProfile from markdown if present | ✅ Fully compatible |

**Key Principle:** All existing single-score paths continue working identically. Profile parameter is purely additive.

---

### 4.4 Env/Config

No new environment variables. Configuration via existing and extended YAML:

| Variable        | Default | Description           | File | Status | Required |
| --------------- | ------- | --------------------- | ---- | ------ | -------- |
| assignments (1-10 legacy) | See templates | Classification-level assignments | [assignment-rules.template.yml](../../templates/assignment-rules.template.yml) | EXISTING | Yes |
| resource_capabilities | See 4.2 | **NEW:** Resource capability definitions | [assignment-rules.template.yml](../../templates/assignment-rules.template.yml) | NEW (extends existing) | Yes (Phase 2) |

---

### 4.5 Backward Compatibility Strategy

**Critical: This project is additive, not replacement.** Existing classification system continues unchanged.

#### Single-Score Mode (Completely Unchanged)

- Existing classification entry points in [auto-fill.ts](../../scripts/utils/roadcrew/auto-fill.ts) and [issue-classification.ts](../../scripts/utils/roadcrew/issue-classification.ts) continue working identically
- Zone boundaries preserved in [classification-zones.ts](../../scripts/utils/roadcrew/classification-zones.ts): 1-3→ai-solo, 4-6→ai-led, 7-8→ai-assisted, 9-10→ai-limited
- `determineAssigneeByClassification()` lookup table in [assignment-rules.yml](../../config/assignment-rules.yml) remains primary interface
- All existing scripts and commands use the single-score path by default

#### Dual-Mode Execution Path

Commands can accept either:
1. **Legacy path (default):** classification (number) → lookup in assignment-rules → single assignee
2. **New path (optional):** task profile → resource filtering → multiple options with confidence

Example flow for Phase 4+ commands:
```
IF profile provided in issue metadata:
  USE recommendAssignments(profile, resourcePool) → multiple options
ELSE:
  USE determineAssigneeByClassification(classification, type, rules) → single assignee
  (optionally convert to profile via classificationToProfile bridge for reference)
```

#### Adoption Timeline

- **Phase 0-1:** New infrastructure isolated in new modules; no impact on existing code
- **Phase 2-3:** Resource capability system built; assignment recommender available as alternative
- **Phase 4:** Integration layer added to commands; existing single-score paths still primary
- **Phase 5+:** Profile validation and calibration optional features for teams opting in
- **Long-term:** Profile becomes primary after team adoption; single-score remains available indefinitely

#### Bridge Function Strategy

`classificationToProfile()` enables teams to:
- Convert existing single-score classifications to profiles without breaking changes
- Gradually migrate by opting in to profile-aware commands
- Fall back to single-score if profile adoption stalls

---

## 5. Execution Plan & Issues

### 5.1 Implementation Plan (≤60 words each phase)

**Phase 0: Audit & Compatibility Layer** – Identify all commands/scripts consuming classifications: [scope-release](../../scripts/commands/scope-release.ts), classify-feedback, [enrich-release](../../scripts/enrich-release.ts), and others. Build adapter layer so new `recommendAssignments()` coexists with existing `determineAssigneeByClassification()`. Verify no breaking changes. Create test matrix of legacy paths through all commands.

**Phase 1: Core Profile Model** – Implement TaskProfile interface, dimension scoring, and classification derivation formula in `scripts/utils/roadcrew/task-profile.ts` (NEW). Create `classification-bridge.ts` (NEW) for bidirectional conversion. Extend [classification-zones.ts](../../scripts/utils/roadcrew/classification-zones.ts) (EXISTING) with profile support. Unit tests verify formula produces expected classifications from dimension inputs and reverse conversion generates reasonable dimension estimates.

**Phase 2: Resource Modeling** – Build ResourceCapability definitions in `resource-pool.ts` (NEW) and management system. Extend [config/assignment-rules.yml](../../config/assignment-rules.yml) (EXISTING) schema with `resource_capabilities` section. Define default capabilities for AI agents (Claude Opus, Sonnet) and human skill levels. Implement capability threshold checking logic. Unit tests verify resource filtering based on profile dimensions.

**Phase 3: Assignment Logic** – Create `assignment-recommender.ts` (NEW) with `recommendAssignments()` function. Implement confidence scoring and reasoning generation. Handle edge cases: no valid resources, multiple equal options, cost optimization. Integration tests with various profile and resource combinations.

**Phase 4: Integration & Bridge** – Extend [auto-fill.ts](../../scripts/utils/roadcrew/auto-fill.ts) (EXISTING) to extract TaskProfile from issue markdown. Modify [classification-zones.ts](../../scripts/utils/roadcrew/classification-zones.ts) (EXISTING) to use profiles when available. Update [scope-release](../../scripts/commands/scope-release.ts) (EXISTING) to generate profiles. Ensure existing single-score path still works. Integration tests verify backward compatibility across all commands.

**Phase 5: Validation & Learning** – Implement profile validation rules in `task-profile.ts` (NEW extension) to catch inconsistent dimensions. Add actual vs estimated tracking for calibration. Create calibration reports showing prediction accuracy. Build feedback loop for dimension refinement based on completion data. Create `calibration-report.ts` (NEW).

**Phase 6: Documentation & Tooling** – Update [context/narratives/classification/classification-guide.md](../../memory-bank/requirements/source-docs/classification/classification-guide.md) (EXISTING) with dimension definitions and examples. Create interactive `scripts/cli/profile-wizard.ts` (NEW). Build `scripts/migrate-to-profiles.ts` (NEW) for converting legacy classifications to profiles. Provide training materials with real codebase examples.

### 5.2 Issues (reference anchors)

- [Issue ROADCREW-001.0](#issue-ROADCREW-001-0): Audit classification consumers & build compatibility adapter
- [Issue ROADCREW-001.1](#issue-ROADCREW-001-1): Implement TaskProfile data model and classification derivation
- [Issue ROADCREW-001.2](#issue-ROADCREW-001-2): Build resource capability modeling and management
- [Issue ROADCREW-001.3](#issue-ROADCREW-001-3): Create assignment recommendation engine with reasoning
- [Issue ROADCREW-001.4](#issue-ROADCREW-001-4): Integrate profiles into existing classification workflow
- [Issue ROADCREW-001.5](#issue-ROADCREW-001-5): Add profile validation and completion tracking
- [Issue ROADCREW-001.6](#issue-ROADCREW-001-6): Build tooling, documentation, and migration support

### 5.3 Risks & Mitigations

| Risk           | Mitigation         |
|----------------|-------------------|
| Existing commands break during Phase 4 integration | Extensive integration test matrix; Phase 0 audit identifies all consumers; adapter layer ensures dual-mode execution |
| Team resists multi-dimensional complexity | Make profiles optional; default to legacy mode with upgrade path; Phase 6 wizard reduces friction |
| Inconsistent dimension scoring across team | Provide calibration sessions with real tasks scored collaboratively; Phase 5 calibration reports guide refinement |
| Resource capability definitions inaccurate | Start conservative (Phase 2); adjust based on actual completion data (Phase 5) over 2-3 sprints |
| Assignment recommendations don't match reality | Track recommendation vs actual assignment; tune thresholds quarterly based on Phase 5 calibration data |

---

## 8. Issue Breakdown

### Issue ROADCREW-001.0: Audit Classification Consumers & Build Compatibility Adapter {#issue-ROADCREW-001-0}

**Overview:** Before implementing new task profile system, audit all commands and scripts consuming classifications from [issue-classification.ts](../../scripts/utils/issue-classification.ts) and [auto-fill.ts](../../scripts/utils/roadcrew/auto-fill.ts). Build adapter layer enabling dual-mode execution (legacy single-score AND new profile-based paths coexist).

**Consumer Audit Checklist:**
- [ ] [scope-release.ts](../../scripts/commands/scope-release.ts) — Uses classification for complexity scoring
- [ ] [enrich-release.ts](../../scripts/enrich-release.ts) — May use for enrichment context
- [ ] classify-feedback command — Likely uses for classification assignment
- [ ] Any GitHub workflow automation using classifications
- [ ] Custom scripts in [scripts/](../../scripts/) referencing issue-classification functions
- [ ] Template processors in [scripts/utils/roadcrew/](../../scripts/utils/roadcrew/) using auto-fill

**Accepts:**
- Complete audit checklist identifying all classification consumers
- Adapter layer design document showing how legacy + new paths coexist
- Test matrix mapping each consumer through both single-score and profile paths
- Verification that no consumers will break if functions receive optional profile parameter
- Documentation of which functions MUST be updated vs which are backward compatible automatically

**Tech Approach:**
- Run ripgrep against codebase: `rg "determineAssigneeByClassification|getZoneForScore|classificationToProfile"` to find direct callers
- Build compatibility wrapper if needed to prevent signature changes from breaking callers
- Create test suite exercising each consumer with legacy inputs only (verifying it still works)
- Document assumption: Phase 1+ will make profile parameters optional (never required)

**Files/Components:** audit-report.md (NEW), adapter-layer.ts (NEW if needed), test matrix (NEW)

**Dependencies:** None (pure analysis)

**Classification:** 2 (ai-solo: Clear audit work, deterministic)

**Size/Complexity:** S/Low

---

### Issue ROADCREW-001.1: Implement TaskProfile Data Model {#issue-ROADCREW-001-1}

**Overview:** Create TaskProfile interface with four objective dimensions and bidirectional conversion logic to/from existing 1-10 classification system for backward compatibility.

**Accepts:**
- **NEW:** `scripts/utils/roadcrew/task-profile.ts` with TaskProfile interface and helper functions
- **NEW:** `scripts/utils/roadcrew/classification-bridge.ts` with conversion functions
- TaskProfile interface defined with determinism, contextBreadth, verificationCost, domainKnowledge fields (all 1-10)
- `createProfile()` validates dimensions (1-10) and calculates **derived** (read-only) classification field
- `profileToClassification()` uses weighted formula: `determinism*0.3 + context*0.25 + verification*0.25 + domain*0.2`
- `classificationToProfile()` converts single score to estimated dimensions based on zone; produces classification match
- Zone mapping preserved: 1-3→ai-solo, 4-6→ai-led, 7-8→ai-assisted, 9-10→ai-limited (references [classification-zones.ts](../../scripts/utils/roadcrew/classification-zones.ts))

**Tech Approach:**
- Create `scripts/utils/roadcrew/task-profile.ts` with TaskProfile interface and validation
- Implement `createProfile()` with dimension validation and classification calculation
- Build `scripts/utils/roadcrew/classification-bridge.ts` with bidirectional conversion functions
- For reverse conversion: ai-solo→high determinism (8-10), ai-limited→high context+domain (8-10)
- Write Jest tests comparing derived classifications to current zone boundaries
- Add tests verifying round-trip: classification→profile→classification preserves zone
- Link tests to [classification-zones.ts](../../scripts/utils/roadcrew/classification-zones.ts) zone definitions

**Files/Components:** 
- **NEW:** task-profile.ts, classification-bridge.ts, task-profile.test.ts
- **EXISTING (ref only):** [classification-zones.ts](../../scripts/utils/roadcrew/classification-zones.ts), [issue-classification.ts](../../scripts/utils/issue-classification.ts)

**Dependencies:** None (new isolated modules)

**Classification:** 3 (ai-solo: Clear data modeling, formula implementation, deterministic)

**Size/Complexity:** M/Low

---

### Issue ROADCREW-001.2: Build Resource Capability Modeling {#issue-ROADCREW-001-2}

**Overview:** Define ResourceCapability interface and create management system for tracking what AI agents and human skill levels can reliably handle per dimension. Extend [assignment-rules.yml](../../config/assignment-rules.yml) with resource capability definitions.

**Accepts:**
- **NEW:** `scripts/utils/roadcrew/resource-pool.ts` with ResourceCapability interface and management
- ResourceCapability interface with max thresholds per dimension
- Default capability definitions for AI agents (Claude Opus, Sonnet) based on industry research and safe estimates
- Human capability definitions for junior, mid-level, senior skill levels
- **MODIFIED:** [config/assignment-rules.yml](../../config/assignment-rules.yml) schema includes new `resource_capabilities` section with YAML validation
- `resource-pool.ts` loads and validates capabilities from configuration file
- Existing legacy assignments (classification-1 through classification-10) remain in config untouched

**Tech Approach:**
- Create `scripts/utils/roadcrew/resource-pool.ts` with ResourceCapability interface
- Implement `loadCapabilities()` and `validateCapabilities()` functions
- Define safe defaults based on research: AI max determinism=4, context=6, verification=5, domain=4
- Human junior: context=6, senior: all dimensions=10 (conservative initially)
- Extend [config/assignment-rules.template.yml](../../config/assignment-rules.template.yml) with resource_capabilities section
- Write tests for capability loading, validation, and threshold checking
- Create migration guide for teams adding capabilities (template provided)

**Files/Components:** 
- **NEW:** resource-pool.ts, resource-pool.test.ts
- **MODIFIED:** [config/assignment-rules.template.yml](../../config/assignment-rules.template.yml) (add resource_capabilities section)
- **REFERENCED:** [assignment-rules.template.yml](../../templates/assignment-rules.template.yml) as base

**Dependencies:** ROADCREW-001.1 (TaskProfile interface)

**Classification:** 4 (ai-led: Requires domain knowledge validation, threshold tuning)

**Size/Complexity:** M/Medium

---

### Issue ROADCREW-001.3: Create Assignment Recommendation Engine {#issue-ROADCREW-001-3}

**Overview:** Implement recommendation logic that generates multiple valid assignment options from TaskProfile and ResourcePool, with confidence scoring and reasoning.

**Accepts:**
- **NEW:** `scripts/utils/roadcrew/assignment-recommender.ts` with `recommendAssignments()` function
- **NEW:** `AssignmentOption` interface with resource, confidence, reasoning fields
- `recommendAssignments()` filters resources by capability thresholds across all dimensions
- Confidence scoring: high if all dimensions ≤70% of max, medium if ≤90%, low otherwise
- Reasoning strings explain why each resource can/cannot handle task (e.g., "Determinism 3 within AI threshold of 4, context 5 within 6")
- Handle edge cases: no valid resources returns empty array with explanation in rationale
- Cost optimization when multiple equal-confidence options available considers costPerHour if defined

**Tech Approach:**
- Create `scripts/utils/roadcrew/assignment-recommender.ts` with `recommendAssignments()` function
- Implement dimension threshold checking: resource valid if all `max_*` ≥ profile dimensions
- Calculate confidence based on "headroom": distance from threshold
- Generate reasoning: automated explanation of why resource matches or doesn't match each dimension
- For cost optimization: sort valid options by costPerHour when defined
- Write tests for various scenarios: perfect match, near threshold, no valid options, cost-optimized selection
- Integration test with [resource-pool.ts](../../scripts/utils/roadcrew/resource-pool.ts) (Phase 2)

**Files/Components:** 
- **NEW:** assignment-recommender.ts, recommender.test.ts

**Dependencies:** ROADCREW-001.1 (TaskProfile), ROADCREW-001.2 (ResourceCapability)

**Classification:** 5 (ai-led: Business logic with edge cases, needs validation)

**Size/Complexity:** L/Medium

---

### Issue ROADCREW-001.4: Integrate Profiles into Classification Workflow {#issue-ROADCREW-001-4}

**Overview:** Extend [auto-fill.ts](../../scripts/utils/roadcrew/auto-fill.ts) and [scope-release.ts](../../scripts/commands/scope-release.ts) to extract and use TaskProfile while maintaining full backward compatibility with existing single-score classifications.

**Accepts:**
- **MODIFIED:** [auto-fill.ts](../../scripts/utils/roadcrew/auto-fill.ts) adds `parseClassification()` to extract dimension subscores from markdown if present
- **MODIFIED:** `autoFillIssue()` accepts optional `profile?: TaskProfile` parameter; falls back to legacy behavior if not provided
- **MODIFIED:** [scope-release.ts](../../scripts/commands/scope-release.ts) generates TaskProfile when analyzing issues; includes in output
- **MODIFIED:** [classification-zones.ts](../../scripts/utils/roadcrew/classification-zones.ts) functions accept optional profile parameter; use if available
- Existing single-score paths continue working identically to current behavior
- All existing commands using these functions produce identical output when profile not provided
- **NEW:** Integration tests covering both legacy (single-score) and new (profile) paths
- **NEW:** Fallback logic documented: "if profile present use it, else use classification number"

**Tech Approach:**
- Extend `auto-fill.ts` `parseClassification()` to look for dimension fields in markdown (determinism:, contextBreadth:, etc.)
- Modify `autoFillIssue()` signature with optional `profile?: TaskProfile` parameter
- Update [scope-release.ts](../../scripts/commands/scope-release.ts) to call `createProfile()` when generating issue metadata
- Add optional profile parameter to `getZoneForScore()` in [classification-zones.ts](../../scripts/utils/roadcrew/classification-zones.ts)
- Implement fallback logic: if profile present use it, else use classification number
- Write integration tests covering both legacy (single-score only) and new (profile + single-score) paths
- Verify existing commands produce identical behavior when profiles not provided

**Files/Components:** 
- **MODIFIED:** [auto-fill.ts](../../scripts/utils/roadcrew/auto-fill.ts), [scope-release.ts](../../scripts/commands/scope-release.ts), [classification-zones.ts](../../scripts/utils/roadcrew/classification-zones.ts)
- **NEW:** integration-tests.test.ts for dual-mode verification

**Dependencies:** ROADCREW-001.1 (TaskProfile and bridge functions), ROADCREW-001.0 (audit complete)

**Classification:** 5 (ai-led: Integration work with backward compatibility critical)

**Size/Complexity:** L/Medium

---

### Issue ROADCREW-001.5: Add Profile Validation and Tracking {#issue-ROADCREW-001-5}

**Overview:** Implement cross-dimension validation rules and actual vs estimated completion tracking to enable profile calibration and continuous improvement.

**Accepts:**
- **MODIFIED/EXTENDED:** [scripts/utils/roadcrew/task-profile.ts](../../scripts/utils/roadcrew/task-profile.ts) adds `validateProfile()` function with anti-pattern detection
- `validateProfile()` checks anti-patterns: determinism<3 + verification>7 flags warning
- Validation catches: context>8 + domain<3, or all dimensions within 2 points (too narrow)
- **NEW:** ValidationResult interface with warnings array and suggestions
- Actual completion time stored in `profile.actualHours` when issue closed
- `calibrationDelta` calculated as `(actual - estimated) / estimated` percentage
- **NEW:** `calibration-report.ts` generates reports showing prediction accuracy trends over time
- Reports segment by dimension and zone to identify systematic biases

**Tech Approach:**
- Add `validateProfile()` to `task-profile.ts` with heuristic rules
- Define ValidationResult interface with warnings[] and suggestions[]
- Implement anti-pattern checks based on industry patterns: high context needs high domain knowledge
- Extend GitHub issue metadata capture to record actual hours on completion (likely via close event)
- Calculate calibration delta when actual data available: `(actual - estimated) / estimated`
- Create `scripts/utils/roadcrew/calibration-report.ts` for trend analysis
- Write tests for known anti-pattern detection and accuracy calculation
- Integration with [scope-release.ts](../../scripts/commands/scope-release.ts) to show calibration when available

**Files/Components:** 
- **MODIFIED/EXTENDED:** task-profile.ts (add validateProfile)
- **NEW:** calibration-report.ts, validation.test.ts, calibration.test.ts

**Dependencies:** ROADCREW-001.1 (TaskProfile interface)

**Classification:** 4 (ai-led: Rule implementation with clear specifications)

**Size/Complexity:** M/Medium

---

### Issue ROADCREW-001.6: Build Tooling and Documentation {#issue-ROADCREW-001-6}

**Overview:** Create interactive profile wizard, update documentation with dimension definitions, and build migration tooling for converting legacy classifications to profiles.

**Accepts:**
- **MODIFIED:** [context/narratives/classification/classification-guide.md](../../memory-bank/requirements/source-docs/classification/classification-guide.md) includes dimension descriptions with examples at levels 1, 5, 10
- **NEW:** `scripts/cli/profile-wizard.ts` — interactive CLI wizard guiding through dimension assessment with contextual help
- **NEW:** `scripts/migrate-to-profiles.ts` converts existing single-score classifications to reasonable dimension breakdown
- **NEW:** Training materials demonstrating profile usage with real codebase examples
- **NEW:** Migration guide with before/after examples
- Clear documentation that profiles are optional; teams can continue using single-score indefinitely
- Backward compatibility clearly documented with adoption path

**Tech Approach:**
- Update [context/narratives/classification/classification-guide.md](../../memory-bank/requirements/source-docs/classification/classification-guide.md) with dimension sections from industry research
- Create `scripts/cli/profile-wizard.ts` using inquirer/commander for interactive prompts
- Build `scripts/migrate-to-profiles.ts` using `classificationToProfile()` bridge function from Phase 1
- Migration heuristics informed by current zone definitions and completion data (Phase 5 calibration)
- Create training deck with before/after examples from actual repository
- Document profile optional: can continue using single-score indefinitely
- Update [README.md](../../README.md) with link to complexity-spec.md and adoption guide
- Add reference to this spec in [.cursorrules.md](../../.cursorrules.md) classification section

**Files/Components:** 
- **MODIFIED:** [context/narratives/classification/classification-guide.md](../../memory-bank/requirements/source-docs/classification/classification-guide.md), [README.md](../../README.md), [.cursorrules.md](../../.cursorrules.md)
- **NEW:** profile-wizard.ts, migrate-to-profiles.ts, training-materials.md

**Dependencies:** All previous issues (complete implementation needed)

**Classification:** 6 (ai-led: Technical writing with human review, examples need validation)

**Size/Complexity:** L/Medium

---

## Editor Instructions:
- TaskProfile is **objective task characterization** separate from worker assignment
- Existing 1-10 classification becomes **derived, read-only field** from profile dimensions
- Assignment is function: `assign(profile, resources) → options[]`
- Full backward compatibility: single-score mode continues working unchanged
- Resource capabilities model what AI and humans can reliably handle **per dimension**
- Phases 0-3 are isolated; Phase 4 integration is where backward compatibility verification happens
- All existing files remain; new files are additive in new `scripts/utils/roadcrew/` modules