To Spec

agentic-workflows-blueprint.workflow.mattpocock.to-spec

Goal

Goal

Synthesize orientation briefs, grilling decision logs, domain models, technical research spikes, and prototype learnings into a rigorous, unambiguous executable technical specification saved at docs/tasks/task.<reference>.md.

Scope

• Applies to: Transforming conceptual discovery and research artifacts into executable implementation specifications and task breakdowns.
• Does not cover: Direct code execution or preliminary discovery (use upstream Matt Pocock skills or execution phase).

Triggers

• "/to-spec"
• "Convert findings to executable spec"
• "Generate specification from prototype and domain model"
• "To-spec conversion"

Inputs

• wayfinderBrief: Orientation brief (wayfinder.md).
• decisionLog: Grilling decision log (decision-log.md).
• domainModel: Domain entity & state machine specification (domain-model.md).
• researchReport (optional): Technical research spike report (research-spike.md).
• prototypeReport (optional): Prototype retrospective (prototype-report.md).
• projectSlug: Short identifier for the repository.

Invariants (Guardrails)

1. Unambiguous Task Mapping: Every task in docs/tasks/task.<reference>.md must specify exact target file paths, explicit dependencies, step-by-step code changes, and verification commands.
2. Enforce UUIDv7 Identity Standards: Ensure all data models, schemas, and resource IDs in the spec mandate UUIDv7 for time-ordered sorting.
3. Strict Phase Gating: The generated specification (docs/tasks/task.<reference>.md) must obtain explicit user approval before execution (Phase 9 of embed-aihero-radioactive).
4. Isolated Task File Path: Save specifications under docs/tasks/task.<reference>.md to avoid cluttering root and prevent overwriting tasks from other sessions.

Procedure

1) Consolidate Upstream Evidence

1. Gather all upstream artifacts: wayfinder.md, decision-log.md, domain-model.md, research-spike.md, and prototype-report.md.
2. Verify that all critical unknowns have been resolved and domain entities have UUIDv7 primary keys.

2) Structure Technical Specification (docs/tasks/task.<reference>.md)

Produce a structured task specification file at docs/tasks/task.<reference>.md formatted as follows:

markdownCopy code
# Technical Specification & Execution Plan: <Feature Title>

## 1. Executive Context & Objectives
- **Goal**: Clear 1-2 sentence objective.
- **Scope**: Explicit In-Scope vs. Out-of-Scope boundaries.
- **Key Invariants**: UUIDv7 primary keys, security rules, performance SLA.

## 2. Architecture & Domain Model
- Summary of entities, UUIDv7 schemas, state machines, and API endpoints.
- Embedded Mermaid ER / State diagrams from Phase 3.

## 3. Sequential Task Breakdown
- [ ] Task 1: <Task Title>
  - **Target Files**: `path/to/file.ext`
  - **Dependencies**: None / Task X
  - **Changes Required**: Detailed description of code/schema edits.
  - **Verification Command**: `npm run test` or `bun test path/to/spec`

- [ ] Task 2: <Task Title>
  - **Target Files**: `path/to/file.ext`
  - **Dependencies**: Task 1
  - **Changes Required**: Detailed description of edits.
  - **Verification Command**: `npm run test`

## 4. Quality Assurance & Test Strategy
- Unit test requirements, integration tests, and performance/security verification steps.

## 5. Rollback & Operational Safety Playbook
- Pre-change snapshot commands, change window constraints, and step-by-step rollback procedures.

3) Review & Sanity-Check Specification

1. Verify that all target file paths exist or have parent directories defined.
2. Ensure task dependencies form a directed acyclic graph (DAG) without circular loops.
3. Confirm that verification commands are non-interactive and testable.

4) Present Specification & Gate on User Approval

1. Present docs/tasks/task.<reference>.md to the user.
2. Gate on explicit user approval before proceeding to Phase 8 (Blueprint Contract) and Phase 9 (Execute).

Outputs

• docs/tasks/task.<reference>.md: Comprehensive technical specification and execution breakdown ready for implementation.

Review gate

• All upstream artifacts (wayfinder, decision log, domain model, research, prototype) integrated.
• Tasks contain exact file paths, explicit edits, and verification commands.
• UUIDv7 primary key standard enforced for all data models.
• Specification presented to user and explicit approval obtained.

References

• ../../../SKILL.md
• ../domain-modeling/SKILL.md
• ../prototype/SKILL.md
• ../../plan-to-blueprint/SKILL.md
• ../../embed-aihero-radioactive/SKILL.md