Architecture Spec Writer

Architecture Spec Writer

Purpose

Turn a chosen architecture into a document that is strong enough to guide implementation.

This skill is for:

• architecture specs
• design docs
• tech specs
• engineering design records
• implementation-facing system design documents

The output should function as a contract:

• what is being built
• what is not being built
• what must remain true
• how components interact
• how correctness is validated
• how rollout happens
• what is still unresolved

Use when

Use this skill when:

• the target architecture is already mostly chosen
• the user wants the design written down cleanly
• implementation will likely happen in multiple sessions or by multiple actors
• ambiguity around interfaces, rollout, observability, or validation needs to be removed

Typical trigger phrases:

• "собери design doc"
• "сделай tech spec"
• "оформи архитектуру в документ"
• "напиши инженерный спек"
• "write a design doc for this architecture"
• "prepare a technical spec"

Do not use when

Do not use this skill for:

• choosing between architecture options
• generic brainstorming
• product PRDs or roadmap docs
• implementation milestone planning
• bug fixing
• repository exploration with no design-writing goal

If the user has not yet chosen an architectural direction, use an architecture-options-analysis skill first. If the user already has a design and now needs phased execution, use an implementation-plan skill instead.

Inputs

Expected inputs:

• chosen architecture or target design direction
• current system context
• affected modules, interfaces, or flows
• explicit constraints
• any existing notes, diagrams, or partial design text

Optional inputs:

• migration constraints
• backward compatibility expectations
• SLO, latency, throughput, or reliability constraints
• ownership boundaries
• deployment constraints
• compliance or security requirements

Outputs

Always produce:

1. a written spec document in the repository
2. the path to that document
3. a compact summary for the user
4. a list of unresolved questions if the design is not fully closed

Document principles

The document must be:

• implementation-oriented
• concrete
• minimal
• explicit about boundaries
• explicit about risks
• explicit about validation
• explicit about unresolved points

The document must not:

• add speculative abstractions
• hide uncertainty behind broad language
• include generic filler
• over-specify details that do not affect implementation

Constraints

• Treat the chosen architecture as the anchor; do not reopen options analysis unless the design is clearly inconsistent.
• Prefer existing repository design-doc conventions when they exist.
• Keep the spec self-contained enough that later implementation sessions can use it as durable project memory.
• If a section does not change implementation, rollout, observability, or validation, it probably does not belong.
• Open questions must be material; do not use them as a dumping ground for low-value thoughts.

Procedure

1. Reconstruct the design context. Before writing the spec, identify:

   • what exists now
   • what is changing
   • what is already decided
   • what remains undecided
   • which parts of the system are affected

2. Identify the document scope. Make clear:

   • what this spec covers
   • what it intentionally does not cover
   • whether the spec is for one module, one subsystem, or a cross-cutting change

3. Choose the document location. Prefer existing repository conventions. Otherwise use:

   • docs/design/<short-slug>.md
   • or another architecture/design-doc folder already used in the repo

4. Write the document as an engineering contract. The spec must contain:

   • Title
   • Goal
   • Non-goals
   • Current state
   • Target design
   • Invariants
   • Interfaces / contracts
   • Data flow / control flow
   • Dependencies
   • Failure modes
   • Rollout / migration plan
   • Observability
   • Validation plan
   • Open questions

5. Make the goal precise. State:

   • the problem being solved
   • the intended outcome
   • the key success condition Avoid broad motivation sections that do not change implementation.

6. Write strong non-goals. Explicitly rule out adjacent work that is not part of this design. Non-goals must constrain implementation scope, not just decorate the document.

7. State invariants. Capture the properties that must remain true after the change, for example:

   • API compatibility guarantees
   • consistency requirements
   • ordering guarantees
   • idempotency
   • latency or reliability expectations
   • ownership or security boundaries

8. Describe interfaces and contracts concretely. For each important boundary, describe:

   • inputs and outputs
   • shape, schema, or types
   • ownership
   • call or dependency direction
   • compatibility expectations
   • error behavior where relevant

9. Describe data flow and control flow. Explain:

   • where requests or data enter
   • how they move through the system
   • where transformations happen
   • where state is read or written
   • where coordination, retries, batching, caching, or queuing happen Keep this operational, not rhetorical.

10. List dependencies and assumptions. Include:

• internal module dependencies
• external services or libraries
• infrastructure assumptions
• runtime assumptions
• deployment or storage assumptions

11. Enumerate failure modes. Include realistic failure modes such as:

• partial writes
• stale caches
• schema mismatch
• retries and duplication
• timeout or overload paths
• ordering bugs
• rollout incompatibility
• monitoring blind spots

For each major failure mode, specify at least one mitigation or detection path.

12. Specify rollout and migration. Make rollout concrete:

• what changes first
• whether dual-path support is needed
• whether backfill or migration is needed
• what can be rolled back
• where compatibility shims exist
• how to cut over safely

13. Specify observability. The spec should define:

• what metrics matter
• what logs or traces are needed
• what failure signals should surface quickly
• what success indicators confirm healthy rollout

14. Specify validation. The validation plan must be lightweight but credible. Prefer:

• focused unit tests
• narrow integration checks
• schema or contract validation
• smoke tests
• migration-specific checks

Avoid broad heavy validation unless the design truly depends on it.

15. End with open questions. Only include open questions that materially affect implementation or rollout. Do not use this section as a dumping ground.

Decision rules

Contract rule

If a section does not change implementation, validation, rollout, or operations, it probably does not belong in the spec.

Non-goal rule

A weak non-goals section means the implementation boundary is still unclear.

Interface rule

If an interface is important enough to change implementation, it must be written explicitly.

Failure-mode rule

If a realistic failure mode is omitted, the spec is incomplete.

Rollout rule

If the change cannot be deployed in one clean step, the spec must describe the transition.

Validation rule

Every architecturally meaningful behavior change should have a named validation path.

Minimality rule

Do not add extra architecture, patterns, or abstractions to make the document look more sophisticated.

Optional subagent use

For larger systems, explicitly spawn bounded subagents before finalizing the spec:

• one subagent to map current interfaces and affected modules
• one subagent to inspect rollout and compatibility surface
• one subagent to identify observability and validation hooks

Wait for the memos, then write the final document. Do not spawn subagents for a small local design doc.

References

Use the supporting references when needed:

• references/spec-template.md
• references/interfaces-and-invariants-checklist.md
• references/rollout-observability-validation-checklist.md

Definition of done

• A spec document exists in the repository.
• Scope and non-goals are explicit.
• Invariants, interfaces, failure modes, rollout, observability, and validation are concrete enough to guide implementation.
• Open questions are real and materially relevant.
• The document reads like an engineering contract, not generic architecture prose.

Required final response format

Return:

• Spec document: <path>
• Goal
• Non-goals
• Main interfaces
• Main failure modes
• Rollout shape
• Validation shape
• Open questions

Positive examples

Use this skill for:

• "собери design doc"
• "сделай tech spec по выбранной архитектуре"
• "оформи модуль в инженерный документ"
• "напиши architecture spec"
• "turn this chosen design into an implementation-facing spec"

Negative examples

Do not use this skill for:

• "сравни варианты архитектуры"
• "сделай план реализации по этапам"
• "почини баг"
• "сделай summary"
• "распиши roadmap"