Civic InnovationsWhat Does a Good Spec File Look Like?
Most legacy government systems exist in a state of profound documentation poverty. The knowledge lives in the heads of retiring employees, in COBOL comments from 1987, in binders that may or may not reflect current behavior. Against this baseline, the question of what makes a “good” spec file takes on different dimensions than it might in greenfield development.
Common Elements
Any spec worth writing answers the fundamental question: what are we building and why? Beyond that, good specs share a few specific characteristics:
Clear success criteria. Not just features, but how you’ll know the thing works. This matters especially when AI agents are generating implementations—they need something concrete to validate against.
Constraints and boundaries. What’s out of scope. What technologies or patterns to use or avoid. Performance requirements. AI tools are prone to scope creep and assumption-making without explicit boundaries.
Examples of expected behavior. Concrete inputs and outputs, edge cases, error states. These serve as both specification and implicit test cases.
Context about the broader system. How this piece fits into what exists. AI assistants lack awareness of surrounding code and architectural decisions unless you tell them.
The SpecOps Context
When modernizing legacy government systems, specs serve a different purpose than typical development documentation. They’re not just implementation guides—they are artifacts that preserve institutional knowledge. This changes what “good” looks like.
A SpecOps specification document must work for multiple audiences simultaneously: domain experts who verify that the spec captures policy intent, software developers and AI coding agents who need precision to generate correct implementations, and future humans who need to understand why the system behaves a certain way years from now—possibly after everyone currently involved has moved on.
That last audience is the one most spec formats neglect entirely.
Three States, Not One
Legacy system specs can’t just describe “what the system does.” They need to distinguish between:
These three things can be in alignment or tension at any moment. And that alignment can shift over time without the code changing—a policy update tomorrow can transform compliant behavior into a violation.
Known Deviation Patterns
Consider the example of a benefits system that should verify income against a state tax agency records, but the legacy system only captures self-reported income because the integration with the tax agency was never built. A good spec would make this explicit:
Policy requirement: Per [directive], applicant income must be verified against tax agency records prior to benefit approval.
Current implementation: Self-reported income only. Applicant provides income information on Form X.
Deviation reason: No interface to tax agency income verification service exists. Integration requested in 2019, not funded.
Modernization note: Modern implementation should include tax agency income verification integration.
This surfaces the gap, documents why it exists, and gives the modernization effort clear direction—without pretending the legacy system does something it doesn’t.
Explicit Ambiguity as a Feature
There’s something that seems almost radical about a methodology that says write down what you don’t know. Traditional documentation can project false confidence. It often describes how things should work and quietly omits the messy parts.
A spec that explicitly marks areas of tension or uncertainty is more honest, more useful for risk assessment, and a better starting point for modernization. It’s an invitation for future clarification rather than a false endpoint.
A spec with unresolved tension is better than no reviewable documentation at all.
Policy Grounding
Government system specs need explicit links to authorizing statutes, regulations, or directives. Not just “these items are excluded from income calculations” but “per 42 USC § 1382a, the following items are excluded from income calculations”
This is the why that survives personnel turnover. It’s what allows future teams to evaluate whether behavior that was correct five years ago still aligns with current policy.
Decision Records
When domain experts verify a spec, they make judgment calls—especially where legacy behavior diverges from current policy understanding. Those decisions need to be captured in the spec, not in a separate document that gets lost.
The spec becomes the repository of institutional reasoning, not just institutional behavior.
Accessible or Precise?
The SpecOps approach says that specs should be “readable by domain experts while detailed enough to guide implementation.” This is genuinely hard.
Options include stratified specs (plain-language summaries with expandable technical detail), executable specs (written as tests that are simultaneously human-readable and machine-verifiable), or annotated specs (a single verbose document where technical precision is explained inline).
Given that the spec is meant to be the source of truth that outlasts implementations, keeping everything in one artifact—even at the cost of verbosity—reduces the risk of layers drifting apart over time.
The Road Ahead
We’re still in early days. Questions remain open:
- How granular should policy references be?
- What’s the right way to represent known deviations?
- How should specs age—versioning, or is git history enough?
- What level of detail helps AI agents versus adding noise?
These will get answered empirically as more agencies adopt the approach. The methodology will evolve. The important thing is to start—to surface questions that were previously invisible, to give future teams something to interrogate rather than nothing at all.
Because the knowledge is what matters. Everything else is implementation details.
#ai #artificialIntelligence #chatgpt #governmentServices #legacySystems #systemModernization
Chris Woody Woodruff
