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:

   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

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