# Clarify Domain Docs

> Clarifies project language and durable decisions, then records them in CONTEXT.md and ADRs. Use when a plan has fuzzy terms, domain concepts are overloaded, user wants shared language, or decisions should be captured before implementation.

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

---


# Clarify Domain Docs

Resolve language and decisions before implementation.

Ask one question at a time. If code can answer the question, inspect the code instead of asking.

## Process

1. Read existing `CONTEXT.md`, `CONTEXT-MAP.md`, and relevant ADRs.
2. Identify overloaded, vague, or conflicting terms.
3. Challenge terms against code and docs.
4. Propose one canonical term and definition.
5. Update `CONTEXT.md` when a term is resolved.
6. Offer an ADR only for decisions that are hard to reverse, surprising, and trade-off driven.

Use [context-format.md](references/context-format.md) and [adr-format.md](references/adr-format.md) only when writing.

## Rules

- `CONTEXT.md` is a glossary, not a spec.
- Keep definitions one or two sentences.
- Do not include implementation details in glossary entries.
- Do not create ADRs for obvious or temporary choices.
- If multiple contexts exist, update the relevant context only.

## Output

End with:

- resolved terms
- changed docs
- decisions recorded or deliberately not recorded
- remaining open questions