Spec Kit: from testable intent to traceable acceptance
Build an append-only convergence notebook before connecting a coding agent
Practice traceable gap handling with a pure synthetic model that preserves existing tasks, allocates new IDs and separates assessment from code changes.
What you will learn
- Model the write contract, not an imaginary intelligent assessor
- Make source references and limitations visible
- Turn the notebook into a readable review aid
Before you start
- Basic requirements, Git and testing concepts
- Understanding of local development versus application deployment
Trace a small feature from intent to evidence and distinguish workflow contracts from verified behavior.
Key takeaways
- Test preservation separately from semantic assessment.
- A source reference explains why a new task exists.
- A synthetic append model is not proof of agent compliance.
Model the write contract, not an imaginary intelligent assessor
A useful learning project takes an existing task document and already-reviewed synthetic findings, then previews the appended convergence phase. It does not infer requirements, inspect a real codebase or decide whether a feature is correct. This separates formatting and preservation behavior from the much harder assessment problem.
The upstream command requires new IDs above the existing maximum, a new phase after existing phases and no changes to earlier tasks. With no actionable findings, tasks.md must remain byte-for-byte unchanged. These are concrete invariants that a small model can test without using an agent.
Make source references and limitations visible
Our companion model accepts a constrained Markdown task format and reviewed findings with source references, gap types and severity. It places constitution violations first, then sorts by severity, allocates IDs and returns a new string. It deliberately rejects malformed findings instead of pretending to repair arbitrary input.
Twelve synthetic cases cover unchanged output, existing IDs and phases, traceability, ordering, invalid input and input preservation. This is our teaching model, not the upstream implementation or a full Markdown parser. It does not guarantee that a real model will obey an append-only instruction.
Turn the notebook into a readable review aid
Present each source reference, observed gap, proposed task and verification status in a table. A small before-and-after view is more useful than a decorative three-dimensional scene because the important relationship is textual traceability. Keep unknown observations visible and require a reviewer to approve the findings.
A later integration could gather evidence from a sandboxed project, but file writes, agent execution and publication should remain separate explicit steps. The prototype here performs no network calls, changes no real task document and creates no repository issues or releases.
Decision guide
| Criterion | Option A | Option B |
|---|---|---|
| Best when | You need predictable behavior and easy auditing | You need adaptive optimization and have reliable telemetry |
| Main risk | May leave performance on the table | Can become difficult to explain or debug |
Implementation steps
- 1
Prepare a synthetic task document and reviewed findings.
- 2
Check unchanged output when there are no findings.
- 3
Preview IDs, ordering and source references.
- 4
Keep mutation and live assessment outside the prototype.
Copy-ready example
{
"teachingModel": true,
"existingTask": "T007",
"finding": {
"source": "FR-002",
"gap": "missing",
"severity": "HIGH"
},
"nextTask": "T008",
"realFileWrite": false,
"semanticAssessment": false
}Frequently asked questions
Does the notebook discover missing implementation automatically?
No. It receives synthetic findings that were already supplied.
Does it run Spec Kit or write tasks.md?
No. It is a pure string model with no upstream execution or real file writes.
Sources
- Spec Kit / templates/commands/converge.mdSource checked 2026-09-14