# Understanding

> ALWAYS invoke this skill before any spec-tree work to load methodology. NEVER create, read, or modify spec tree files without loading this foundation first.

- Skill: `outcomeengineering/understanding` (Agent Skill, multi-file: 17 files)
- Install (CLI): `npx skillmds@latest add outcomeengineering/understanding`
- Raw SKILL.md: https://api.skillmd.com/api/skills/outcomeengineering/understanding/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: outcomeengineering (https://skillmd.com/u/outcomeengineering)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/outcomeengineering/understanding

---


<objective>

Load the Spec Tree methodology into the conversation so all subsequent skills operate from a shared foundation. This is a foundation skill — it loads once and emits a marker that other skills check before starting work.

</objective>

<quick_start>

Invoke `/understanding` before any spec-tree work. The skill reads 3 core reference files and emits a `<SPEC_TREE_FOUNDATION>` marker. If the marker is already present in the conversation, skip.

</quick_start>

<principles>

1. **TRUTH FLOWS DOWN** — Specs declare. Tests derive from specs. Code derives from tests. When layers disagree, the lower layer is in violation. Never weaken a spec to match code or tests. Read `references/durable-map.md`.
2. **FOUNDATION, NOT CONTEXT** — This skill loads methodology; it does not load project-specific artifacts. Use `/contextualizing` for target-specific context injection.
3. **LOAD ONCE** — Check for `<SPEC_TREE_FOUNDATION>` marker before loading. If present, skip.
4. **SPECS ARE DECLARATIONS** — The Spec Tree is a durable, declarative map. Nothing moves, nothing closes. Specs declare product truth.
5. **TWO NODE TYPES** — Enablers (infrastructure) and outcomes (hypothesis + assertions). No other node types exist. Read `references/node-types.md`.
6. **ASSERTIONS SPECIFY OUTPUT** — Assertions specify what the software does, locally verifiable by automated tests or agent review. Assertions derive from PDRs/ADRs, not from code or tests.
7. **DETERMINISTIC CONTEXT** — The tree structure defines what context an agent receives. No keyword search, no heuristics. This is handled by `/contextualizing`.
8. **ATEMPORAL VOICE** — Specs state product truth. Never narrate history. Flag temporal language as a quality issue.

</principles>

<workflow>

1. Check conversation for `<SPEC_TREE_FOUNDATION>` marker. If present, skip — already loaded.
2. Read core references (always loaded):
   - `references/durable-map.md` — truth hierarchy, declarative model, atemporal voice, node states
   - `references/node-types.md` — enabler vs outcome, directory structure
   - `references/assertion-types.md` — scenario, mapping, conformance, property, compliance
3. Note operational references (loaded on demand by other skills):
   - `references/decomposition-semantics.md` — when to nest, depth heuristics (used by `/decomposing`)
   - `references/ordering-rules.md` — sparse integer ordering, dependency encoding (used by `/authoring`, `/decomposing`)
   - `references/what-goes-where.md` — ADR/PDR/spec/test content taxonomy (used by `/aligning`)
   - `references/excluded-nodes.md` — `spx/EXCLUDE` convention, quality gate integration (used by `/authoring`, `/testing`)
4. Note template and example locations (read only when authoring):
   - `templates/product/product-name.product.md`
   - `templates/decisions/decision-name.adr.md`
   - `templates/decisions/decision-name.pdr.md`
   - `templates/nodes/enabler-name.md`
   - `templates/nodes/outcome-name.md`
   - `examples/` — concrete filled specs (read when you need to see what a completed spec looks like)
5. Emit the `<SPEC_TREE_FOUNDATION>` marker:

```text
<SPEC_TREE_FOUNDATION>
Loaded: durable-map, node-types, assertion-types
Operational references available: decomposition-semantics, ordering-rules, what-goes-where, excluded-nodes
Templates available: product, adr, pdr, enabler, outcome
Examples available in: examples/
</SPEC_TREE_FOUNDATION>
```

</workflow>

<success_criteria>

- [ ] Three core reference files read and understood
- [ ] Operational reference, template, and example locations known
- [ ] `<SPEC_TREE_FOUNDATION>` marker emitted
- [ ] Methodology loaded: truth hierarchy (PDR/ADR → Spec → Test → Code), lower layer is always in violation when layers disagree
- [ ] Methodology loaded: enabler vs outcome distinction, three-part hypothesis structure
- [ ] Methodology loaded: atemporal voice principle, prohibited temporal markers
- [ ] Methodology loaded: five assertion types (scenario, mapping, conformance, property, compliance) and selection criteria

</success_criteria>