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.

Status Lifecycle

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

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.