Before engineering starts, an IntentSpec should clear six blocking readiness gates: a meaningful title, a specific objective, testable outcomes, at least one hard constraint, an edge case with expected behavior, and concrete verification. Add evidence references, scope, health metrics, and decision history when they improve the judgment, but do not confuse useful enrichment with the calibrated minimum for implementation.
A spec landed in the queue with a tidy feature list: add filters, add a saved-views menu, add CSV export. The agent built all three cleanly. The team later learned that users needed one report to send itself every Monday. The spec was detailed, but it never named the outcome the features were supposed to create.
The minimum is judgment, not document length
A useful spec does not need to be long. It needs to answer the questions the coding agent should not invent while implementing. Pathmode's preflight turns that standard into six deterministic gates.
The six blocking gates
- Meaningful title — a specific name for the change, not “new feature” or “misc fixes.”
- Specific objective — the actor, present problem or capability, and why the work matters.
- Testable outcomes — observable state changes after success, not a list of implementation activities.
- Hard constraints — at least one boundary the implementation can actually violate, or an applicable workspace constitution rule.
- Edge-case coverage — a failure or boundary scenario paired with the expected behavior.
- Concrete verification — at least one check specific enough for an agent or reviewer to run.
These gates answer whether the stated decision is ready to implement. They do not answer whether it is the best product decision. An agent can draft and challenge the content; a human still authorizes the judgment.
The gate reports. The human decides.
Important fields that are not universal blockers
- Evidence references ground the objective and outcomes in tickets, interviews, observations, metrics, or research. Evidence is optional in the verdict because not every valid change begins with customer evidence.
- Scope defines what this implementation may and may not touch. It matters most when an otherwise reasonable solution could sprawl or cross a permission boundary.
- Health metrics name what must not degrade while the new outcome improves. They are useful when success creates a measurable tradeoff, not as compulsory filler.
- Decisions and rejected alternatives preserve judgment that a later agent might otherwise reopen accidentally.
- Implementation findings carry contradictions discovered during the build back into refinement instead of burying them in a chat transcript.
Put it in the repository
Save the reviewed IntentSpec as intent.md beside the code it governs. The file should contain the decision and safe references, not private transcripts or sensitive customer data. Connected Pathmode teams can keep that evidence, named guest feedback, and signed-in authorization behind the file while the repository remains authoritative for implementation.
Run the preflight before the first edit and again whenever the product decision changes. A changed objective or outcome should invalidate stale confirmation rather than inherit approval from older wording.
Frequently asked questions
- What are the six readiness gates?
- Title, objective specificity, outcome testability, hard constraints, edge-case coverage, and concrete verification. Pathmode grades these deterministically, so the same IntentSpec gets the same verdict without a model call.
- Is evidence required before an agent starts?
- Evidence is optional in the readiness verdict but valuable for grounding and review. A small internal refactor may have no customer evidence. A consequential product decision should normally reference the tickets, observations, metrics, or research that informed it.
- What about scope and health metrics?
- Include scope when the implementation needs a permission boundary, and health metrics when pursuing the new outcome could degrade an existing one. They are first-class IntentSpec fields, but they are not universal blocking gates for every change.
- Isn't verification an engineering concern?
- The implementation details are, but the spec should name how success can be demonstrated. Defining the fastest check, stronger tests, manual fallback, shipped signal, and regression guard before coding gives the agent and reviewer a shared meaning of done.