Compose Domain Knowledge Article — Intent Map Synthesis Layer

You are creating or restructuring a domain-level synthesis in the person's Intent Map — a short, navigable map of one area of their project's documentation: what subsystems exist, how they connect, and why they matter. The whole reason this exists is the general rule for harness documentation: it can't just be one massive document — it needs to be nested and structured and organized in a way that's both agent-friendly and human-readable. This is that rule applied to one domain at a time.

For adding a single artifact/entry to an existing domain, use /intent-map-docs-add instead. This skill is for the heavier lift of composing or restructuring the domain itself.

Where It Lives

This works on whatever documentation the person already has. Ask, or check, where their project's intent/knowledge docs already live; if they don't have a convention yet, the reasonable default is <project>/docs/intent-map/{domain-name}/, with the master index at <project>/docs/intent-map/INDEX.md. Once you know the person's real root, use it consistently for the rest of this task — don't mix the default in with an existing convention.

If the folder doesn't exist yet: say so plainly ("You don't have a domain-map folder yet — want me to start one from what's already in your repo?") and offer to build the first INDEX.md from the docs, folders and code that already exist, rather than assuming the structure below is already in place.

CRITICAL: Organization Is By System/Intent, NOT By Lifecycle Status

The primary organizational axis is what the thing IS — which system, which subsystem, which tool. NOT whether it's active, experimental, or validated.

Lifecycle status (active, experimental, validated, open-question, deferred) belongs in the frontmatter of each individual artifact document — not as the folder structure.

WRONG:

checkout-flow/
├── active/
│   └── payment-step.md
├── validated/
└── experiments/

RIGHT:

checkout-flow/
├── INDEX.md
├── one-page-checkout/
│   ├── INDEX.md
│   └── payment-step.md      (status: active in frontmatter)
├── multi-step-checkout/
│   ├── INDEX.md
│   └── address-first.md     (status: experimental in frontmatter)

When someone drills into a domain, they should see the actual subsystems — not a sorting by status. Status is metadata, not structure.

Artifact Frontmatter Schema

Every document MUST have:

---
title: "{Human-readable title}"
artifact-type: "{system | tool | subsystem | pattern | decision | reference | config}"
domain: "{parent domain slug}"
status: "{active | validated | experimental | open-question | deferred | deprecated}"
last-verified: "{YYYY-MM-DD}"
primary-repos: ["{repo-name}"]
---

INDEX.md Structure (the synthesis document)

The INDEX.md is the map of the domain. It leads with intent and links to subsystems.

# {Domain Name}

## Intent

{What are we trying to accomplish with this domain? What human experience does it serve?}

## Subsystems

{List each subsystem with a link and one-line intent description}

- [[subsystem-name/INDEX]] — {what this subsystem is trying to accomplish}
- [[subsystem-name/INDEX]] — {intent description}

## Connections to Other Domains

{What other domains does this touch? What breaks if this changes?}

## For Agents Working Here

{What to read first. What tools to use. Common mistakes.}

How to Research Before Writing

1. If a memory-search tool is set up (see /alignment-harness:harness-setup), run it with domain keywords to surface recent work. Otherwise, grep/search the repo itself, past Claude Code sessions under ~/.claude/projects/*/*.jsonl, and git log for the same keywords, and say plainly that no memory-search tool was configured.
2. Read existing artifacts in the domain folder.
3. If an intent database is set up (/intent-db), check it for related UX intents. Otherwise skip this step and say so.
4. Check the project's own CLAUDE.md (or equivalent conventions doc) for domain-specific rules.
5. If an /insight-style oracle is set up, query it for institutional principles. Otherwise reason from what you found in steps 1-4 and say the oracle step was skipped.

Never treat a skipped step as "nothing to find" — say which step didn't run and why, then proceed with what you do have.

TOKEN BUDGET: 30% research, 70% writing. Write as you go — don't exhaust context on research.

When to Use This vs /intent-map-docs-add

Situation	Skill
Creating a new domain from scratch	This skill
Restructuring an existing domain's folder layout	This skill
Building the INDEX.md synthesis for a domain	This skill
Adding one system/tool to an existing domain	/intent-map-docs-add
Documenting a tool you just built	/intent-map-docs-add