context-anchoring

# Context Anchoring

## Scope

> Feature-level only — anchors decisions as a feature flows from design → implementation → bugfix → refactor.

## Config Resolution

This skill manages a directory of per-feature context docs. Resolution order:

1. Read `.lattice/config.yaml` in the repo root.
2. If found and `paths.context_base` is set → use that directory as the context base (the Create behavior creates it on demand).
3. If there is no config file or no `paths.context_base` key → use the default `.lattice/context/`.

Each feature gets one doc at `<context_base>/<feature-name>.md`. No default principles, no overlay modes, no override files -- just a thin template and per-feature docs that grow through enrichment.

## Why Context Anchors Exist

AI has no persistent memory across sessions. Early decisions get contradicted, naming drifts, and the "why" evaporates -- a forgotten decision becomes a potential contradiction, a lost constraint becomes a violation, an unresolved question becomes a silent assumption.

Context anchor docs prevent this by being:

- **Feature-bound** -- one doc per feature, scoped decisions only
- **Decision-focused** -- capture what, why, and what-else-was-considered for every choice
- **Append-only** -- decisions are never removed or rewritten, only added chronologically
- **Session-spanning** -- the doc outlives the conversation and carries context forward
- **Git-native** -- lives in the repo, versioned alongside code

Two documents per feature: the **requirement doc** (static, written upfront, not managed by this skill) defines *what* to build; the **context anchor doc** (living, evolving, managed by this skill) captures *how* and *why* -- decisions, constraints, reasoning that emerge during development.

The requirement doc may live in this repo or in whatever system the team already tracks requirements in (Jira, Linear, a wiki) -- this atom never writes to it regardless of where it lives.

## Document Lifecycle

Three behaviors govern the context anchor doc's lifecycle. Each is triggered reactively (user asks) or proactively (AI suggests). In both cases, the AI **always confirms before acting** -- propose, user disposes.

| Behavior | Purpose | Reactive Trigger | Proactive Trigger |
|----------|---------|-----------------|-------------------|
| **Create** | Start a new context doc | User asks to create one | AI detects feature work beginning without a doc |
| **Load** | Restore context from an existing doc | User asks to load/resume | AI detects existing docs and suggests loading |
| **Enrich** | Add a new decision, constraint, or resolution | User asks to capture something | AI detects a decision made in conversation |

## Status Lifecycle

Every context doc carries a `status` frontmatter field. Never infer status from body prose.

| Value | Set by |
|---|---|
| `draft` | `context-anchoring` Create — design not yet complete |
| `approved` | `design-blueprint` Step 3 — L1–L4 complete, design reviewed |
| `complete` | `code-forge` Step 5 — implementation done |

**STOP: Check this field before acting on a context doc.** `draft` ≠ approved. `approved` ≠ complete. Deviation from an approved design → update the doc and re-approve — no new status values exist.

## Create Behavior

Always confirm before creating.

**Steps**:

1. **Identify the feature name.** Derive the kebab-case filename from it (e.g., "User Authentication" → `user-authentication.md`). Confirm the name with the user.
2. **Ask about the requirement doc.** If the user has one, capture it for the `requirement_doc` frontmatter field -- a local file path, or an external reference (URL, ticket ID, or other identifier resolvable via a connected MCP tool). If neither, leave `null`.
3. **Create `<context_base>/`** if it does not already exist.
4. **Generate from template.** Read `./assets/feature-doc-template.md` and fill in:
   - Frontmatter: `feature`, `requirement_doc`, `created` (today's date), `status: draft`
   - H1 heading: feature name
   - Summary: one-line description (ask the user or derive from context)
   - If the template file is not found, generate the doc using this minimal structure:
     ```
     ---
     feature: <feature-name>
     requirement_doc: <local path, external reference, or null>
     created: <today's date>
     status: draft
     ---
     # <Feature Name>
     <one-line summary>
     ## Decisions Log
     | Date | Decision | Reasoning | Alternatives Considered |
     |------|----------|-----------|------------------------|
     ## Open Questions
     None.
     ## Constraints
     None.
     ## Key Files
     ```
5. **Confirm creation.** Show the user the proposed path and a content summary.

## Load Behavior

Always confirm before loading.

**Steps**:

1. **Read the context doc.** Parse the frontmatter and all sections.
2. **Resolve the linked requirement doc** if `requirement_doc` is not null. Local path → read directly. External reference (URL, ticket ID, or other identifier) and a connected MCP tool can resolve it → attempt the fetch. Neither applies → ask the user to paste the current requirement constraints directly -- expected, not an error. Use whatever is resolved to understand feature goals and scope, but do not modify it.
3. **Present the structured acknowledgment** (see Output Formats below):
   - Feature name and summary
   - **Status** (from the frontmatter `status` field — surface explicitly)
   - Requirement doc status (linked or not linked)
   - Decision count and latest decision
   - Open questions (if any)
   - Constraints (if any)
4. **Honor all logged decisions.** Every decision in the log is an active commitment. Never contradict a logged decision without explicit discussion and a new decision entry explaining the change.
5. **Respect constraints as non-negotiable.** Constraints are harder than decisions -- they represent boundaries that cannot be crossed without a deliberate, documented override.
6. **Flag open questions when work touches them.** If the