Skip to content
sdlc

Surface system shape; don't hide it

Status: open/published

Summary

Section titled “Summary”
  • The system publishes its own structure: a reader (human or agent) walking docs/ can derive what sdlc thinks it is without reading code or asking a maintainer.
  • Discoverability is a value, not an afterthought.
  • Every entity registered in the data model; every milestone ordered in index; every new artifact pattern gets an index file when there are more than two instances.

Statement

Section titled “Statement”

An SDLC-defined system publishes its own structure. A reader (human or agent) walking docs/ should be able to 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. Discoverability is a value, not an afterthought.

Why

Section titled “Why”

At present, the ability for a human to understand a software system is still necessary.

Good documentation and architecture for humans also translates into better context for LLM agents. This structured approach facilitates better, more reliable tooling.

To be expanded. The core insight: a system whose shape is visible only to insiders rots invisibly. The cost of writing the self-publishing artifacts (D-ORMG-data-model.md, docs/index.md, per-entity reference docs, ADRs, Standards) is paid once; the cost of not writing them is paid every time someone needs to derive structure from scratch.

How it applies

Section titled “How it applies”

To be expanded. Initial scope:

  • System concepts are modeled as ‘entities’
  • Entities have location, schema, and prose descriptions; they all have consistent expectations.
  • Every entity-kind will have reference documents covering schema, relationships, extension points and workflow invariants (S-0005-entity-definition-contract).
  • Architectural decisions live as ADRs in docs/planning/decisions/; rules live as Standards in docs/planning/standards/; values live as Principles 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?’
  • docs/planning/decisions/D-ORMG-data-model.md: full five-layer roster of entities sdlc plans to support, with status per row.
  • docs/index.md: hierarchical TOC with section transclusions, so the index stays in sync with the canonical sources; single source of truth for milestone order (by version — the roadmap manifest is retired per D-ORMG-data-model).
  • docs/dashboard.base: surfaces which files still need review via the need_human_review flag.

Implications

Section titled “Implications”

Strong connection to P-0005-schema-over-prose: structured metadata is what makes the system queryable; self-publishing the structure of that metadata is the next layer up. Strong connection to P-0006-self-hosting-development: a self-hosting system can only stay coherent if it can read its own shape.

Notes

Section titled “Notes”

The recurring pattern in this planning session of expressing structure as discoverable artifacts (D-ORMG-data-model.md, roadmap.md (since retired into index), principle index in M0000) is what suggested elevating this to a Principle.

← Back to Principles