engineering-insights

Engineering Insights — Session Capture

Captures what you learned this session into the repository's INSIGHTS.md file(s) so the next session starts smarter. This skill makes no assumption about the repo's module layout — it discovers where insights should go from the repository itself.

Where insights live (discover, don't assume)

Find the target file(s) for the areas the session touched, in this order:

1. Existing insights files — git ls-files '**/INSIGHTS.md' (or find . -name INSIGHTS.md -not -path '*/node_modules/*'). Prefer the one closest to the code you changed.
2. A documented convention — if the repo's CONTRIBUTING.md, ARCHITECTURE.md, or a package README names where session notes go, follow that.
3. Otherwise, place by area — one INSIGHTS.md at the root of the top-level package or directory that changed (e.g. next to that area's package.json / source root). If the change spans several areas, update the insights file nearest each.
4. Ambiguous? Ask the user where insights should live before creating a new file.

If a session touched multiple areas, update each relevant file.

Workflow

Capture Progress:
- [ ] Step 1: Identify which areas of the repo were touched this session
- [ ] Step 2: Reflect — extract raw learnings (see categories below)
- [ ] Step 3: Quality-check each entry (see standards below)
- [ ] Step 4: Locate/read the existing INSIGHTS.md for each area (if any)
- [ ] Step 5: Append new entries; never overwrite existing ones
- [ ] Step 6: Confirm entries are concrete, dated, and non-redundant

Step 1 — Identify touched areas

git diff --name-only HEAD 2>/dev/null || git status --short

Group the changed files by their top-level directory / package. Those groups are the "areas" you will capture insights for.

Step 2 — Reflect and extract

For each area, identify discoveries in one of these four categories:

• PATTERNS — approaches that worked reliably; reusable techniques.
• MISTAKES — errors made and how they were fixed; what to avoid next time.
• DECISIONS — architectural or design choices made, and why.
• CONTEXT — project-specific quirks, constraints, non-obvious wiring.

Each entry must name a concrete file, function, or command — not a general principle.

Step 3 — Quality standard

Bad (vague)	Good (specific)
"Be careful with async"	"jobs/queue.ts must await the insert before notify() — fire-and-forget drops rows under load"
"Migrations can be tricky"	"Migrations never auto-run on boot — run the migrate command first; the #1 first-run failure"

Reject an entry if: it could apply to any project of this kind, lacks a file path or function name, or is already written down in the repo's docs.

Step 4 — Read the existing file

cat <path>/INSIGHTS.md 2>/dev/null || echo "(file does not exist yet)"

Check for duplicates. If an existing entry covers the same point, add a dated correction note rather than a new entry.

Step 5 — Append entries

NEVER use the Write tool on an existing INSIGHTS.md — that overwrites accumulated history.

• File exists → use Edit to insert the new entry under the correct section heading (## Patterns, ## Mistakes, …), immediately below that heading.
• File does not exist → use Write (only this case) with this template:

# INSIGHTS.md — <Area Name>

Session learnings accumulated over time. Treat as high-confidence guidance.
Read before working in this area. Update at session end via /engineering-insights.

---

## Patterns

## Decisions

## Mistakes

## Context

## Open Questions

Each entry:

### YYYY-MM-DD — <one-line summary>
<Concrete observation. Include a file path or function name. One to three sentences.>

Step 6 — Final check

• Every entry names a file, function, or command.
• No entry restates generic programming knowledge.
• Nothing duplicates an existing entry or a rule already in the repo's docs.
• Each entry fits in 1–3 sentences.

Cadence

Session type	Action
30+ min session with discoveries	Always run
Trivial single-file fix, no surprises	Skip
Bug whose root cause was non-obvious	Always capture in Mistakes
Architecture decision made	Always capture in Decisions

Quarterly maintenance

When an INSIGHTS.md exceeds ~50 entries, consolidate: merge related entries, remove outdated workarounds for fixed bugs, and promote stable patterns into the repo's long-lived docs.