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 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 current task involves an area with an unresolved question, surface it immediately. Never silently assume an answer.

## Enrich Behavior

Always confirm before writing.

**What to capture in the Decisions Log**:

- **Date** -- when the decision was made
- **Decision** -- what was decided, stated clearly and concisely
- **Reasoning** -- why this choice was made, key factors
- **Alternatives Considered** -- what else was evaluated and why it was rejected

**Rules**:

1. **Append-only.** New entries go at the bottom of the Decisions Log table. Never modify or remove existing entries.
2. **Chronological order.** Entries reflect the order decisions were made, not grouped by topic.
3. **Concise but complete.** Each entry must be understandable on its own without re-reading the full conversation.
4. **Feature-bound only.** Capture only decisions relevant to this specific feature. Cross-cutting concerns, project-wide conventions, and general preferences belong elsewhere.
5. **Resolve open questions explicitly.** When an open question gets answered, add the answer as a decision in the log *and* remove the question from the Open Questions list.
6. **Constraints are non-negotiable.** Once recorded, a constraint binds. Changing a constraint requires a new decision entry explaining why it is being revised.
7. **Constraint Override Protocol.** If the user explicitly says to override a constraint (e.g., "forget that constraint, we've changed direction"), never silently delete it. Instead: (a) ask the user to confirm the override explicitly, (b) strike through the constraint in the Constraints section (prefix with `~~`), and (c) add a decision entry in the Decisions Log recording the override and reasoning. Constraint history preserved; binding status revoked.
8. **Key Files dedup.** When adding to the Key Files table, check whether the path already exists in the table. If it does — skip.
9. **Cross-cutting check.** After enriching, apply the learning-harvest cross-cutting test: (1) does it name a pattern or approach, not a feature-specific fact? (2) could a developer on a different feature apply it without knowing this feature's context? If both pass — silently add it to the learning-harvest queue. Do not prompt the user here.

## Document Discovery

When the user asks to load or resume but does not specify which feature:

1. **Scan the context base directory** for `.md` files.
2. **Match by frontmatter** `feature` field or by filename.
3. **Multiple docs exist** → present a numbered list with feature name, creation date, and decision count. Let the user choose.
4. **Only one doc exists** → suggest loading it. Confirm before proceeding.
5. **No docs exist** → inform the user and suggest creating one.
6. **Fuzzy match**: the user's term partially matches multiple docs (e.g., "auth" matching `user-authentication.md` and `oauth-authentication.md`) → show all partial matches with full filenames and let the user choose. Never guess.

When the user mentions a feature name in conversation, check whether a matching context doc exists. If it does and has not been loaded this session, suggest loading it.

## Output Formats

**Load**: show feature name, **status** (from frontmatter), requirement doc status, decision count, open questions, constraints, latest decision. Close with: "All logged decisions are active. Constraints are non-negotiable. I will flag open questions when work touches them."

**Enrich**: show exactly what will be added (decision, reasoning, alternatives considered). Wait for confirmation before writing.

**Create**: show proposed path, feature name, requirement doc link. Wait for confirmation before creating.

## Integration with Other Skills

This atom is composed by the molecules that orchestrate feature workflows:

- **`design-blueprint`** — invokes **Create** or **Load** in Step 1 (Establish Context), then invokes **Enrich** at each design-level checkpoint to capture decisions as they emerge
- **`code-forge`** — invokes **Load** in Step 1 (Establish Implementation Context), then invokes **Enrich** throughout Steps 3–5 to capture implementation decisions, key files, and resolved questions
- **`refactor-safely`** — invokes **Document Discovery** and **Load** in Step 1, persists the approved refactor plan via **Enrich** in Step 3, and captures final decisions in Step 8
- **`bug-fix`** — invokes **Document Discovery** and **Load** in Step 1, captures diagnosis and repair decisions via **Enrich** in Step 7

When a context doc is active (loaded in the current session), **Enrich** runs continuously -- the AI monitors the conversation for decisions worth capturing and suggests enrichment as they arise. This is not limited to the molecule that loaded the doc; any skill producing decisions can trigger an enrichment suggestion.