dms_tailscalectl/docs/agents/domain.md

Domain Documentation

This project follows the domain documentation conventions used by the interrogate skill.

Expected Layout

Single-context (most common)

/ (project root)
├── CONTEXT.md                 ← canonical glossary and domain model
├── docs/
│   └── adr/                   ← Architectural Decision Records
│       ├── 0001-....md
│       └── ...
└── src/ (or equivalent)

Multi-context (monorepos or large systems)

/ (project root)
├── CONTEXT-MAP.md             ← points to per-context locations
├── docs/
│   └── adr/                   ← system-wide ADRs
├── src/
│   ├── context-a/
│   │   ├── CONTEXT.md
│   │   └── docs/adr/
│   └── context-b/
│       ├── CONTEXT.md
│       └── docs/adr/

Rules for Skills and Agents

Lazy Creation

• Only create CONTEXT.md when the first meaningful term is resolved.
• Only create docs/adr/ (or per-context ADR folders) when the first ADR is actually needed.
• Do not pre-create empty files "just in case".

During Work (especially with interrogate)

• When a term is used that conflicts with existing language in CONTEXT.md, call it out immediately.
• When vague or overloaded terms appear, propose a precise canonical term.
• Stress-test domain relationships with concrete scenarios.
• Cross-check stated behavior against actual code.
• Update CONTEXT.md inline as decisions are made — do not batch updates.

Architectural Decision Records (ADRs)

Only propose creating an ADR when all three are true:

1. The decision is hard to reverse later.
2. A future reader would be surprised without the context.
3. There were genuine alternatives and a real trade-off was made.

Use the format defined in your project's ADR template when creating one.

For Other Skills

Skills such as interrogate, to-prd, architecture review, diagnosis, and TDD should read this file (and the referenced CONTEXT.md / ADRs) to maintain consistent domain language across the project.