Context File

Context File

Create a new .context/ file with standard YAML frontmatter and appropriate sections.

Prerequisites

• A clear understanding of the file type needed: plan (multi-step work), finding (research), analysis (review), or known-issue (a real, verified gap that isn't being fixed right now)
• Familiarity with the .context/ directory structure: plans/, findings/, analysis/, known-issues/
• The context-index skill available for index regeneration after creation

When to Use

• plan: Multi-step implementation, migration, or remediation work with open tasks
• finding: Research output, code review results, audit findings, prerequisite investigations
• analysis: Duplication reports, benchmark results, comparative reviews, one-off audits
• known-issue: A concrete, verified gap or bug that's being consciously deferred rather than fixed now — see session-reflection's workflow, which is the primary source of these

When Not to Use

• For skill remediation plans, use skill-auditor remediate — it produces a richer schema
• Do not store secrets, credentials, or personal data in .context/ files
• Do not create .context/ files for ephemeral notes — use inline comments instead
• Do not create a KNOWN_ISSUE for something you're fixing in the same session — just fix it. KNOWN_ISSUE is for deferred, tracked work only.

Frontmatter Schema

Every .context/ file MUST start with this exact block:

---
title: "Human-readable title"
type: PLAN | FINDING | ANALYSIS | INSTRUCTION | AUDIT | KNOWN_ISSUE
status: DRAFT | ACTIVE | DEFERRED | DONE | SUPERSEDED
date: YYYY-MM-DD
related:
  - relative/path/to/related.md
---

Enum values are UPPER_CASE. Field rules:

• title — prose title matching the H1 heading; wrap in quotes
• type — matches the subdirectory (plans/ → PLAN, findings/ → FINDING, analysis/ → ANALYSIS, known-issues/ → KNOWN_ISSUE; note the underscore vs the hyphenated directory)
• status — DRAFT until reviewed, ACTIVE for in-progress work you would pick up next, DEFERRED for a real not-done item that cannot be actioned yet because it is date-gated or externally blocked, DONE when complete, SUPERSEDED when replaced (for KNOWN_ISSUE: ACTIVE/DEFERRED = still open, DONE = fixed). DEFERRED is not for merely low-priority work — express that with value: LOW on an ACTIVE item. The read protocol ranks DEFERRED strictly below DRAFT/ACTIVE; reactivate to ACTIVE when the blocker clears.
• deferred_until — optional reactivation date (YYYY-MM-DD) for a date-gated DEFERRED item: the date on or after which it should be reconsidered. Only valid with status: DEFERRED. Omit for externally-blocked items with no known ripen date. The read protocol does not list an item whose deferred_until is still in the future — it is hidden from the pick until then, and surfaces as reactivation-eligible once the date passes. The date takes precedence even if the item is also blocked.
• date — creation date in ISO format; do not update on edits
• related — relative paths from the file's location; omit the key entirely if there are no related files
• severity — required for type: KNOWN_ISSUE only: CRITICAL | HIGH | MEDIUM | LOW. Not applicable to other types.
• value — required for type: PLAN, FINDING, and KNOWN_ISSUE while status is DRAFT, ACTIVE, or DEFERRED: HIGH | MEDIUM | LOW. The benefit-of-action grade, distinct from severity (risk-of-inaction) and effort (cost-of-action). Grade against .context/instructions/value-rubric.md; do not guess. Not applicable to ANALYSIS / INSTRUCTION / AUDIT. Exempt on DONE / SUPERSEDED.
• themes — required for type: PLAN, FINDING, and KNOWN_ISSUE while status is DRAFT, ACTIVE, or DEFERRED: a multi-valued ordered list from EVAL | PR-TOOLING | DOCS | GOVERNANCE | SKILL-QUALITY | DISTRIBUTION. The subject axis (what area the item is about), orthogonal to the magnitude axes. Write it primary-first — themes[0] is the primary theme and the only member used in the read-protocol tie-break. Draw members from .context/instructions/theme-vocabulary.md; do not invent themes. Block YAML style like related. Not applicable to ANALYSIS / INSTRUCTION / AUDIT. Exempt on DONE / SUPERSEDED.

Workflow

1. Determine type: PLAN / FINDING / ANALYSIS / KNOWN_ISSUE
2. Choose a filename: kebab-case for plans (migrate-off-tessl-eval.md), topic-YYYY-MM-DD.md for timestamped reports and known-issues
3. Create the file using the template matching the type below
4. Set status: DRAFT until the content is reviewed (KNOWN_ISSUE starts at ACTIVE — it's already a confirmed, real gap by the time it's written down)
5. Run the context index regeneration script to update the index after creation

Templates

Plan (.context/plans/):

---
title: "Plan: <concise title>"
type: PLAN
status: DRAFT
date: YYYY-MM-DD
---
# Plan: <title>
## Goal
One paragraph describing the desired end state.
## Steps
1. Step one
2. Step two
## Open Questions
- Question one

Finding (.context/findings/):

---
title: "Finding: <topic>"
type: FINDING
status: ACTIVE
date: YYYY-MM-DD
related:
  - ../plans/related-plan.md
---
# Finding: <topic>
> One-sentence summary.
## Summary
## Detail
## Recommended Action

Analysis (.context/analysis/):

---
title: "<Topic> Analysis — YYYY-MM-DD"
type: ANALYSIS
status: DONE
date: YYYY-MM-DD
---
# <Topic> Analysis — YYYY-MM-DD
## Summary
## Findings
## Conclusion

Known Issue (.context/known-issues/):

---
title: "Known Issue: <concrete, verified problem>"
type: KNOWN_ISSUE
status: ACTIVE
date: YYYY-MM-DD
severity: CRITICAL | HIGH | MEDIUM | LOW
value: HIGH | MEDIUM | LOW
themes:
  - GOVERNANCE   # ordered, primary-first; from theme-vocabulary.md
related:
  - ../plans/related-plan.md
---
# Known Issue: <concrete, verified problem>
> One-sentence statement of the verified impact, not a hypothesis.
## Why this exists
## Impact if unfixed
## Suggested fix (not yet applied — this is the tracked issue, not the fix)

Mindset

• Write for the next agent or human who reads this cold — assume no prior context
• status: DRAFT is the safe default; promote to ACTIVE only when reviewed; use DEFERRED for a reviewed item that is real but intentionally parked (date-gated or blocked)
• Date is creation date, not last-modified — do not update it on subsequent edits
• After creating or updating a .context/ file, consider regenerating the index to keep it current
• Use production-grade terminology: pitfall, gotcha, ALWAYS, NEVER, anti-pattern

Troubleshooting

• Pre-commit hook blocks commit: Run check-context-frontmatter.sh to find files missing YAML frontmatter — add the required block and re-run
• Missing from index after creation: Run regenerate-context-index.sh — the index is generated from frontmatter, not file existence alone
• Wrong type directory: Files must live under the matching subdirectory — plans in plans/, findings in findings/, analysis in analysis/, known-issues in known-issues/

Anti-Patterns

NEVER create a .context/ file without the full frontmatter block. WHY: The pre-commit hook will block the commit and the index cannot include the file. BAD: Starting a file with # Plan: ... directly, with no frontmatter. GOOD: Always open with ---\ntitle: ...\ntype: ...\nstatus: ...\ndate: ...\n---.

NEVER include related: [] when there are no related files. WHY: An empty list is noise; the field should be absent. BAD: related: [] GOOD: Omit the related key entirely.

NEVER put findings or plans under .context/audits/. WHY: .context/audits/ is owned by skill-auditor --store; writing there by hand conflicts with the tool's schema. GOOD: Use .context/plans/, .context/findings/, or .context/analysis/ only.

References