pre-commission-alignment

name	pre-commission-alignment
model	sonnet
description	Produces a gap inventory and Track 0 remediation commit that closes mismatches between implementation prompts and actual codebase state, ensuring parallel tracks start from a clean, type-safe foundation. Use when: 'commission these tracks', 'run Track 0 before handing off', 'check for spec-to-code drift', 'align before we build'.
category	specification-driven-development
triggers	["commission these tracks","run Track 0 before handing off","check for spec-to-code drift","align before we build"]
tier	1
agents	["primary"]
tool_dependencies	["file_system"]
inputs	[{"name":"implementation_prompts","type":"string[]","description":"Paths to implementation prompt documents to align against codebase","required":true},{"name":"repo_path","type":"string","description":"Repository root to check for spec-to-code drift","required":true}]
outputs	[{"name":"gap_inventory","type":"string","description":"Gap inventory and Track 0 remediation commit closing mismatches between prompts and actual codebase state"}]

Pre-Commission Alignment

Philosophy

Autonomous implementation agents encounter type errors, missing imports, and API mismatches when specs drift from the actual codebase. Rather than force agents to halt, improvise, or silently diverge, establish clean handoff points through a deliberate quality gate.

The insight: Pre-implementation misalignment is cheap to discover (< 1 day) but catastrophically expensive to debug across parallel tracks (3-5 days of cross-track conflicts). Track 0 isn't bureaucratic friction — it's tactical hygiene that protects all downstream work.

Why this matters for three-agent workflow: When strategy → implementation → tactical fixes handoffs are clean, autonomous work accelerates. When they're dirty, agents thrash. This skill ensures clean handoff discipline.

---

When to Use

Activate this skill when:

• Time gap exists between spec authoring and implementation commissioning
• Codebase changed since specs were written (v0.2.0 → v0.2.1 → v0.2.2 pattern)
• Multi-track commissions share state (all tracks touch the same entities, APIs, or configuration)
• Prompts reference specific types or endpoints that may have been refactored
• You're about to commission > 2 parallel implementation tracks

Do NOT use if the codebase is frozen, specs were written 1 hour ago, or all actors are working from identical, static context.

---

Workflow

Phase 1: Dual-Read (30 min)

1. Read the actual codebase (not the spec doc):

   • Entity definitions, types, enums
   • API routes, middleware, models
   • Configuration, build output, runtime structure
   • Note what exists, not what the spec says should exist

2. Read the prompts (the ones you're about to give to agents):

   • Mark every reference to a type, entity, or endpoint
   • Highlight assumptions about naming conventions
   • Note content types, API patterns, data flow expectations

3. Create a gap inventory (list, not essay):

   MISMATCHES:
   - Prompt assumes EntityType.CUSTOM_TYPE but codebase has Type.VARIANT only
   - Prompt references /api/v2/items but only /api/v1/items exists
   - Import paths in prompt: src/types/X but actual: src/lib/X
   - Prompt expects configSchema.js but actual: config.ts
   

Phase 2: Track 0 Remediation (1-3 hours)