Spec Writing

Spec Writing

Write specifications for this project using a standard template, writing disciplines, and conventions. The audience for all specifications is strictly AI agents — optimize for machine consumption: high signal density, unambiguous normative text, and structured formats over prose.

Constraints

• Specs live in docs/specs/ (subfolders allowed for logical grouping)
• Filenames: lowercase, hyphenated (e.g., authentication.md, job-scheduler.md)
• All template sections required except Known Limitations, which is omitted when not applicable (never include it with "None")
• Acceptance criteria must be verifiable by an agent (observable outcomes, no subjective judgment)
• New specs start with status: draft
• Every normative statement has exactly one home across the spec corpus — no cross-spec duplication

Workflow

1. Ask clarifying questions to gather context about what spec is needed
2. Determine if this spec is standalone or part of a parent/child hierarchy — if part of a hierarchy, identify the parent and establish what content belongs at each level
3. Invoke /doc-coauthoring to develop the spec through structured collaboration
4. Ensure output conforms to the template structure
5. Apply all writing disciplines (see below)
6. If separable concerns exist (multiple distinct features that could be implemented independently), advise splitting into separate specs
7. Before finalizing, verify: no duplication from other specs, all rationale in blockquotes, procedures use step lists, criteria are non-redundant with prose, cross-references resolve

Template

All specs follow this structure:

---
title: <Title>
version: 0.1.0
last_updated: <ISO 8601 date>
status: draft | review | approved | deprecated
---

# <Title>

## Overview

What this is and why it exists.

## Constraints

Hard boundaries. Must/must not. Non-negotiable rules.

## Specification

The core details. What it does, how it works. Precise enough to implement against.

## Acceptance Criteria

- [ ] Given <precondition>, when <action>, then <outcome>

## Known Limitations

Intentional capability gaps, scale boundaries, or deferred items. Include only when applicable —
omit this section entirely otherwise.

## Dependencies

What this relies on to function.

## References

Related specs, external docs, prior art.

Frontmatter

Section Guidance

Writing Disciplines

Define Once, Reference Elsewhere

Every normative behavior has exactly one home in the spec corpus. When another spec needs to mention a behavior owned elsewhere:

1. Write a one-sentence summary of what happens (not how).
2. Add a section-level cross-reference: See [<Spec Name>: <Section>](./<spec-name>#<section-anchor>) for full behavior.

Do not copy procedures, tables, or step lists. If you're writing more than two sentences about a behavior with a normative home elsewhere, you are duplicating.

Parent/Child Layering

Parent specs contain: Architectural decisions, interface contracts, cross-cutting classification tables, technology choices, summary references to child content.

Parent specs do NOT contain: Implementation procedures, detailed type definitions, acceptance criteria that test child-spec behavior.

Rule: If a parent section has a corresponding child section, the parent has only a summary + cross-reference. The child owns the detail.

Rationale Separation

"Why" content must be in blockquote admonitions, visually distinct from normative "what" text:

> **Rationale:** Explanation of why this design decision was made.

Test: Read the Specification with rationale blocks hidden. It should be a complete, implementable spec on its own.

Structured Formats Over Prose

Avoid paragraph-form procedures with inline conditionals.

Acceptance Criteria Discipline

Criteria are for: Edge cases, ordering guarantees, interaction effects, negative cases, error handling paths.

Criteria are NOT for: GWT reformatting of spec prose. If a criterion says the same thing as a prose sentence, delete it.

No parent-child duplication. If a parent delegates to a sub-spec ("See sub-spec for criteria"), the parent has no inline criteria for that topic.

Acceptance Criteria Format

Use Given/When/Then. Each criterion must be verifiable with observable outcomes.

Good examples:

- [ ] Given a stale cache re-fetch fails, when the failure occurs, then the stale data is retained
      and the cache remains stale
- [ ] Given an agent is running for issue N, when issue N is removed, then agentFailed is emitted
      before issueRemoved

Bad examples (restatement of prose):

- [ ] Given the engine starts, when initialization completes, then the TUI renders
- [ ] Given getPRForIssue is called, when a linked PR exists, then it returns PR details

Avoid:

• "Given X, when reviewed, then it is well-written" (subjective)
• "Given X, when tested, then it works correctly" (vague)

Converted and distributed by TomeVault — claim your Tome and manage your conversions.