to-spec

Synthesize a specification from accepted planning authority and codebase understanding. Planning authority may be the current conversation, a supplied Wayfinder map reference, or both. Do not interview the user; use only what the selected sources establish.

Read planning artifact contracts and Work Tracker context assembly before producing the specification. Use the configured Work Tracker and Domain Orientation when their bindings exist; preserve standalone behavior when they do not.

Process

1. Select and load the planning source:

   • With no Work Tracker reference, use the accepted decisions and Domain Model Deltas in the current conversation. This path needs no Wayfinder Map.
   • With a Wayfinder Map reference, invoke the shared Context Assembly contract with the Ticket Origin Repository, Map Context, and the Map's permanent reference. Accept only Complete. If the destination still has open decision tickets or material fog, return it to Wayfinder instead of guessing.
   • When revising or reviewing an existing Specification, invoke the shared contract with the Ticket Origin Repository, Decision Context, and that artifact's permanent reference. Accept only Complete.
   • When conversation and durable sources are both supplied, use the accepted Context Pack file unchanged as the baseline and add only explicitly accepted decisions from the current conversation. Do not repeat provider reads. Return contradictions to planning instead of choosing silently.

   Source selection is complete when every accepted conversation decision remains explicit in the session and every required Context Assembly gate has passed.

2. Perform configured Domain Orientation, then explore the referenced repositories only as needed to understand current state. Use the loaded effective planning language and applicable ADRs throughout.
3. Materialize the complete solution-level Repository References and exhaustive Context Scope established by discovery or planning. Use bounded source validation to resolve their pointers; do not begin new open-ended discovery. Return unresolved material questions to discovery or planning.
4. Sketch out the complete set of seams at which you're going to test the feature. Existing seams should be preferred to new ones. Use the highest seam possible. If new seams are needed, propose them at the highest point you can. The fewer seams across the codebase, the better - the ideal number is one.

When materially different caller-facing ownership, interface, seam, or contract choices remain possible, use the codebase-design skill before proposing the set. For each seam, propose the smallest faithful repository-native test approach and its nearest prior art. Check with the user that the complete seam set and proposed approaches match their expectations; the confirmed records are settled.

5. Record every confirmed repository-local and cross-repository Settled Seam only in Testing Decisions. Preserve full-fidelity Domain Model Deltas, architecture rationale, provenance, and canonical documentation obligations in Context Scope and the applicable decisions.
6. Write the spec using the template below. Before publication, validate the complete settled payload against the planning artifact contracts and publish only when it passes. Use the confirmed artifact mapping to retain a selected Map as the Specification or publish a separate Specification with its selected Authority Sources. A specification is planning authority, not an executable delivery ticket; do not apply an execution Routing Label solely because the specification was published.
7. Invoke fresh shared Context Assembly with the Ticket Origin Repository, Decision Context, and the published artifact's permanent reference. Return a non-complete result to the source or publication step that caused it.

Problem Statement

The problem that the user is facing, from the user's perspective.

Solution

The solution to the problem, from the user's perspective.

User Stories

A concise numbered list of distinct actor goals and benefits established by the accepted sources. Each user story should be in the format of:

1. As an <actor>, I want a <feature>, so that <benefit>

Keep behavioral detail in Acceptance criteria and technical detail in the applicable decisions below. Shortening this list must preserve every source requirement under the planning artifact contracts.

Acceptance criteria

Write the complete source-authorized behavior using the shared acceptance criteria contract. Keep this section after User Stories; retain the existing sections below in full.

Use a short descriptive heading or list entry for each identifier. For example:

AC-1. Preserve the selected rows in an export

When a user exports a report with an active filter, the downloaded file contains exactly the rows matching that filter. Other rows are absent.

This example illustrates presentation only; use the behavior and verification details established by the actual authority.

Repository References

The complete confirmed solution-level set of Repository Reference records. References grant no write authority.

Authority Sources

Permanent references to every governing Map or other planning artifact, or None — direct accepted authority is fully materialized in this Specification.

Context Scope

The complete relevant Context Scope record. If no canonical context applies, write None — <reason>.

Implementation Decisions

Record the accepted implementation decisions. This can include:

• The modules that will be built/modified
• The interfaces of those modules that will be built/modified
• Technical clarifications from the developer
• Architectural decisions
• Schema changes
• API contracts
• Specific interactions

Identify the owning Repository ID for every repository-owned decision. Preserve applicable accepted architecture rationale and rejected alternatives in full.

Do NOT include specific file paths or code snippets. They may end up being outdated very quickly.

Exception: if a prototype produced a snippet that encodes a decision more precisely than prose can (state machine, reducer, schema, type shape), inline it within the relevant decision and note briefly that it came from a prototype. Trim to the decision-rich parts — not a working demo, just the important bits.

Testing Decisions

A list of testing decisions that were made. Include:

• A description of what makes a good test (only test external behavior, not implementation details)
• Every repository-local and cross-repository Settled Seam record

Connect every acceptance criterion to its verification through the existing Settled Seams and Validation Obligations. Identify automated, manual, or combined verification only as established by accepted testing decisions. Retain their complete contracts, owners, methods, prerequisites, prior art, and required evidence. Keep run-specific build references, environment instances, and results in verification requests and evidence; accepted environment constraints remain here.

This is the sole specification section that owns settled seams. Do not add Repository Scope or a separate Cross-Repository Seams section to a specification.

Out of Scope

A description of the things that are out of scope for this spec.

Further Notes

Any further notes about the feature.