# Create Context File

> 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.

- Skill: `pantheon-org/create-context-file` (Agent Skill, multi-file: 25 files)
- Install (CLI): `npx skillmds@latest add pantheon-org/create-context-file`
- Raw SKILL.md: https://api.skillmd.com/api/skills/pantheon-org/create-context-file/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Research & Search
- License: MIT
- Author: pantheon-org (https://skillmd.com/u/pantheon-org)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/pantheon-org/create-context-file

---


# 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
# Link a finding back to the plan it informed
./scripts/create-context-file.sh --type findings --title "Auth token analysis" \
  --related "../plans/2026-03-16-auth-rollout.md"
```

Expected result: a dated finding file whose frontmatter includes a `related:`
list; when no `--related` is given, the key is omitted entirely rather than
written as `related: []`.

```bash
# Follow-up that can't start until a plan lands
./scripts/create-context-file.sh --type follow-ups --title "Wire up token refresh" \
  --blocked-by "../plans/2026-03-16-auth-rollout.md"
```

Expected result: a dated follow-up file whose frontmatter includes a
`blocked-by:` list, in the same "omitted when empty" style as `related`. The
`context-index` skill's `scripts/context-ready.sh` reads this field across
every context file to report which active files have zero open blockers —
set `--blocks` on the file being depended on, `--blocked-by` on the file
doing the depending, or both if the relationship is worth recording from
either side.

```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 emit `related: []`, `blocks: []`, or `blocked-by: []` when there is nothing to list

**WHY:** an empty list is noise; the field should be absent when there is
nothing to link.

**BAD:** `related: []` (or `blocks: []` / `blocked-by: []`) in the frontmatter.
**GOOD:** omit the key entirely; pass `--related`/`--blocks`/`--blocked-by`
only when there is at least one path to list.

**Consequence:** frontmatter clutter that trains readers (and tooling) to
ignore the field, masking the times it actually carries a link.

### NEVER set `blocked-by` on a file whose blocker is unlikely to ever reach `status: done`

**WHY:** `context-ready.sh` fails closed — an unresolvable blocker path, or
one that sits at a status other than `done` indefinitely, keeps the
dependent file reported as blocked forever, with no automatic timeout.

**BAD:** pointing `blocked-by` at a typology whose typical lifecycle is "keep
indefinitely" or "keep while active" rather than a discrete close (see the
lifecycle column in [Typologies](references/typologies.md)) — e.g. a
`guide` or `research` file nobody plans to ever mark `done`.
**GOOD:** point `blocked-by` at a typology whose lifecycle is a real
close event (`plan` retiring, `follow-up` closing, `ticket` tracked to
resolution, `merge-request` retiring after merge) — or record the
relationship in prose instead if it isn't really "done-or-not-done" shaped.

**Consequence:** a file that can never actually be reported ready, with
nothing in `context-ready.sh`'s output explaining that the blocker itself is
the problem rather than the work.

### 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.
- [Frontmatter schema](assets/schemas/context-frontmatter.schema.json) — the JSON Schema for `title`, `type`, `date`, `status`, `tags`, `related`, `blocks`, and `blocked-by`; load when validating a context file's frontmatter or wiring a lint check.