Skip to content
sdlc

Surface system shape; don't hide it

State: open/published

Summary

Section titled “Summary”
  • Every system SDLC defines publishes its own structure in docs/: the entity roster, the work queue, and where decisions live, derivable without reading code or asking a maintainer.
  • Every entity is registered in the data model; every milestone is ordered in index; every new artifact pattern gets an index file once it has more than two instances.

Statement

Section titled “Statement”

An SDLC-defined system publishes its own structure. A reader, human or agent, walking docs/ can derive what the system thinks it is, what entities it tracks, where work is queued, and where decisions live, without reading code, joining a chat channel, or asking a maintainer.

Why

Section titled “Why”

A system whose shape is visible only to insiders rots invisibly. The cost of writing the self-publishing artifacts (the data model roster, docs/index.md, per-entity reference docs, Decisions, Standards) is paid once. The cost of not writing them is paid every time someone, human or agent, derives the structure from scratch. Structure written for humans is also better context for agents and more reliable input for tooling.

How it applies

Section titled “How it applies”
  • Every entity kind has reference documents covering schema, relationships, extension points, and workflow invariants (S-0005-entity-definition-contract). When adding an entity kind, register it in the data model roster and write its reference document before the kind is used in earnest.
  • When a new artifact pattern reaches a third instance, add an index file for it and link that index from docs/index.md. A reviewer rejects the third instance that lands without one.
  • Decisions live in docs/planning/decisions/, rules in docs/planning/standards/, values in docs/planning/principles/. The three locations are discoverable from each other and from the entity roster.

Examples

Section titled “Examples”
  • D-0003-datamodel-categorization: the five-layer entity model with rationale; the canonical answer to “how does SDLC think about its entities?”
  • D-ORMG-data-model: the full roster of entities SDLC supports or plans to, with status per row.
  • docs/index.md: a hierarchical table of contents built from section transclusions, so it stays in sync with its sources; the single source of truth for milestone order (by version).
  • docs/dashboard.base: surfaces which files still need review via the need_human_review flag.

Implications

Section titled “Implications”

← Back to Principles