Appendix A - 23. Epic & design-doc templates

The Structure of Epic & design-doc templates — its shape at a glance:

A stub scaffold materializes the required sections, a lint asserts their presence, and the checked artifact then drives the work — the shape is declared, not remembered.

flowchart LR
  Stub[Stub scaffold] -->|materializes sections| Doc[/Planning artifact/]
  Doc --> Lint{{Section-presence lint}}
  Lint -->|required sections present| Drive([Drives the work])
  Lint -->|a required section missing| Fail([Rejected])

Accessible description: a stub scaffold materializes the required sections into a planning artifact; a section-presence lint checks them; when all are present the artifact drives the work, and when one is missing the artifact is rejected.

Projected from the catalogue entry governance-doc-controls / Epic & design-doc templates.

On this page: Intent · Motivation · Applicability · Structure · Sample Code · Consequences · Example use within DocAble · Related Patterns

Intent

Intent — Fixed section-templates for the two core planning artifacts, Epics (multi-dispatch efforts) and design docs, so every effort is framed with the same required sections (scope, phase decomposition, second-order dynamics, definition-of-done, observability), and the planning artifact drives the work instead of being written after the fact.

Motivation

A planning artifact written free-form omits exactly the sections that matter. The design doc that skips second-order dynamics ships a substrate that deadlocks at tick T+100; the Epic with no explicit Definition-of-Done is "done" by assertion; the design that introduces an event-bus topic with no observability section leaves the substrate unmonitorable. Without a template, each author frames differently and the sections that prevent production incidents are the first to be dropped under time pressure. The failure is incomplete plans whose gaps resurface as incidents.

Applicability

• A repeatable artifact genre worth standardizing. Epics and design docs recur; a one-off memo does not need a template.
• The set of required sections, identified from failure. Each required section earns its place because omitting it caused an incident (a deadlock, a false "done," an unmonitorable substrate).
• A scaffold + lints so the template is materialized and checked; a template that is only described in docs decays to advisory prose.

Structure

The Structure diagram appears at the top of this page.

Sample Code

The template makes required sections structural: a scaffold pre-places them, and a lint checks the artifact carries each. The section list is itself identified from failure — each earns its place because omitting it once caused an incident.

import sys

REQUIRED_SECTIONS = [
    "## Scope",
    "## Phase decomposition",
    "## Second-order dynamics",   # omitting this once shipped a substrate that deadlocked under load
    "## Definition of Done",
    "## Observability",           # required for any design that introduces a new event topic
]

def lint_sections(doc_text: str, introduces_topic: bool) -> list[str]:
    findings = []
    for heading in REQUIRED_SECTIONS:
        if heading == "## Observability" and not introduces_topic:
            continue                                   # conditional: only topic-introducing designs need it
        if heading not in doc_text:
            findings.append(f"missing required section: {heading}")
    return findings

if __name__ == "__main__":
    findings = lint_sections(open(sys.argv[1]).read(), introduces_topic=True)
    print("\n".join(findings))
    sys.exit(1 if findings else 0)

Consequences

• Soft·Hard has a hollow-section hole. A presence check passes an empty "second-order dynamics" heading; the template forces the section, not genuine thought in it.
• Maintenance surface. A new required section means updating the template + the scaffold + the lint together; drift among them yields false rejections or silent gaps.
• Over-templating adds ceremony. Forcing the full Epic shape onto a trivial change is friction the author routes around; the template must be scoped to efforts that warrant it.

Example use within DocAble

• The Epic template (mandatory section shape + the multi-criterion Definition-of-Done).
• The epic-stub scaffold that materializes an Epic dir + ledger registration, with registration gates.
• The design-doc rule that a new event-bus topic requires an observability/event-bus block.
• The rule that any substrate with repetition/concurrency carries a second-order-dynamics section.

Related Patterns

• Counterpart — the Epic Definition-of-Done is the hard gate that verifies, at close, that an Epic's template was actually satisfied (criteria met, pins re-run); the template is the soft shape up front, the DoD is the enforced check at the end.
• Enabler — the template makes second-order-dynamics and observability required sections, so it feeds the reason-about-dynamics and own-your-observability disciplines at design time rather than after an incident.
• See also (family) — rule index and mandatory-snippet-table: sibling governance documents whose completeness is enforced by a hard counterpart.