---
type: note
name: decision-d4-code-is-the-source-of-truth
tags: [architecture, design-decision]
source: .claude/plans/documentation-stack-spec.md
---

# Note: Design decision: Code is the source of truth

## Context

Documentation stack architecture decision.

## Content

`contextual.py`, `discovery.py`, and `suggestions.py`
evolve into **consumers** of the template registry —
they don't get replaced, they get upgraded. Instead of
maintaining their own pattern lists and tip
definitions, they query autogenerated templates that
are derived from code.

The flow becomes:

```text
Code (source of truth)
  -> Template engine (autogenerates content)
    -> Template registry (stores typed templates)
      -> contextual.py (queries Error templates)
      -> discovery.py (queries Tip templates)
      -> suggestions.py (queries Task templates)
```

The existing modules keep their role (contextual
scoring, progressive discovery, post-workflow
suggestions) but their *data source* shifts from
hardcoded lists to the template registry.

## Related Topics

_No related topics yet._
