/context-anchoring

name: context-anchoring
description: "Manage per-feature living documents that capture decisions, constraints, and reasoning across AI sessions during active development. Scoped to feature-level work — design, implementation, bugfix, refactor — not for codebase-wide assessments or product-wide specifications (those define their own document lifecycles). Handles creating new context documents, loading existing ones, and enriching them with new decisions. Use when starting a new feature, resuming work, making technical decisions, resolving questions, or when context needs to persist across sessions. Use this skill whenever the user mentions 'load context', 'update context', 'context doc', 'decisions', 'continue where we left off', 'what did we decide', or 'capture this decision'."

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