create-context-file v1.0.0A

Immutable. This exact content never changes and is served at /api/v1/blob/516d35935a58bc3b.

---
name: create-context-file
description: "Creates a structured, date-stamped context file filed by typology (findings, plans, guides, follow-ups, merge-requests, tickets, decisions, notes, research) with YAML frontmatter. Use when saving a finding, writing a plan, capturing a guide, recording a decision, logging a follow-up, filing a merge-request note, plus ticket write-ups."
license: MIT
metadata:
  version: "1.0.0"
  audience: agents
  workflow: capture, planning, documentation
---

# Create Context File

Persist a working artifact into the project's context directory, filed by
**typology** and named with a date prefix so it sorts chronologically and never
collides.

## When to Use

- Save an investigation write-up, plan, guide, or decision produced while working.
- Capture a follow-up, merge-request note, or ticket write-up for later.
- The user asks to "save this finding", "create a plan", or "write this up".

## When Not to Use

- Do NOT use for technical notes that belong inline in source — write a code comment.
- Do NOT use for permanent, long-lived docs — use the README or docs site.
- Do NOT use for issue tracking — use the issue tracker.
- Do NOT use for content the team consumes externally — use the docs system.

## Principles

1. **Typology is the organizing axis.** ALWAYS choose the folder by *what the
   artifact is*, not by how long it lives.
2. **One artifact, one file.** ALWAYS keep a single typology per file; NEVER
   merge a finding with a plan.
3. **Deterministic names.** The generator MUST own the filename and frontmatter;
   never hand-craft them.
4. **Curated growth.** Extend the typology set deliberately, not per task.

## Workflow

1. Choose the typology from the curated set. — **Stop if:** none fits and the
   need will not recur; reuse the closest match instead of adding a folder.
2. Inspect what already exists for that typology to avoid duplicates:

   ```bash
   ls .context/findings/
   ```

   Expected result: the existing files, so you can confirm none already covers
   this artifact.
3. Run the generator with a specific, task-tied title. — **Verify:** the printed
   path uses the expected typology plus date.
4. Fill in the body beneath the generated heading. — **Stop if:** the content
   spans two typologies; split it into separate files.

## Quick Commands

```bash
# Create a finding with tags
./scripts/create-context-file.sh --type findings --title "Auth token analysis" \
  --tags "auth,oauth"
```

Expected result: a new dated finding file, printed as the only stdout line.

```bash
# Multi-line body via heredoc
./scripts/create-context-file.sh --type plans --title "Retriever rollout" << 'EOF'
## Phase 1
...
EOF
```

Expected result: a dated plan file containing the heredoc body.

```bash
# Preview without writing
./scripts/create-context-file.sh --type merge-requests --title "PROJ-1234" --dry-run
```

Expected result: the target path plus full file body printed; nothing written.

```bash
# A deliberate one-off typology
./scripts/create-context-file.sh --type experiments --title "spike" --allow-new-type
```

Expected result: a file under a new typology folder, created knowingly.

Full option list: see the CLI reference below.

## Anti-Patterns

### NEVER create a file without checking the typology folder first

**WHY:** the same artifact captured twice fragments context and breaks search.

**BAD:** run the generator immediately for a plan that already exists.
**GOOD:** list the folder, confirm nothing covers it, then create.

**Consequence:** duplicate, drifting files that later readers cannot reconcile —
a common pitfall once a repository grows.

### NEVER use a generic slug like `notes` or `todo`

**WHY:** vague slugs collide and read as noise when sorted by date.

**BAD:** `--title "notes"` yields a `notes.md` that clashes across tasks.
**GOOD:** `--title "API refactor findings"` yields a specific, searchable name.

**Consequence:** unsearchable filenames plus silent name clashes in production
repositories.

### NEVER mix typologies in one file

**WHY:** a finding, a plan, and a follow-up have different lifecycles and readers.

**BAD:** one file holding analysis, a rollout plan, and open questions.
**GOOD:** three files, one per typology, cross-referenced if needed.

**Consequence:** no file can be retired cleanly; each keeps stale content alive.

### NEVER hand-edit the filename or frontmatter date

**WHY:** the date prefix plus ISO `date` power sorting and downstream tooling.

**BAD:** rename to drop the date, or set `date: Jul 21st`.
**GOOD:** let the generator produce both; keep the original date on later edits.

**Consequence:** broken chronological ordering plus frontmatter parse failures.

### NEVER invent a new typology for a one-off

**WHY:** ad-hoc folders erode the curated set that makes context navigable.

**BAD:** create a bespoke folder for a single throwaway note.
**GOOD:** reuse the closest typology, or pass `--allow-new-type` knowingly.

**Consequence:** folder sprawl that defeats predictable retrieval — a slow pitfall.

## References

- [Typologies](references/typologies.md) — the curated catalog, selection rule, and how to extend the set; load when choosing or adding a typology.
- [CLI reference](references/cli.md) — full generator flags, behavior, and examples; load when you need an option beyond the Quick Commands.