@nklisch/pi-agile-workflow 0.15.3

package/skills/park/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: park
+description: >
+  ALWAYS invoke this skill when the user wants to capture an idea for later without derailing current
+  work — do not start working on the parked idea inline. Captures short ideas, richer context notes,
+  or roadmap-style multi-arc thoughts into the agile-workflow backlog under .work/backlog/ with
+  minimal frontmatter. Use when a new direction surfaces mid-flow and you shouldn't derail what's
+  currently in progress. Triggers on "park this", "park it", "remind me about X", "add to backlog",
+  "we should consider Y", "save this for later", "let's not lose this".
+---
+
+# Park
+
+You capture an idea into the project's `.work/backlog/` tier without interrupting
+the current work. The captured file is intentionally unscoped — full kind, stage,
+parent, dependency, and decomposition decisions happen later via
+`/agile-workflow:scope`.
+
+## When to invoke
+
+Auto-trigger on capture phrases:
+- "park this", "park the idea of"
+- "remind me about X later"
+- "add to backlog"
+- "we should consider X" (when the user clearly doesn't want to derail current work)
+- "good idea — for later"
+
+If the user is actively scoping or designing the captured idea, use `/agile-workflow:scope`
+instead. Park is for the deferred-consideration case only.
+
+## Workflow
+
+### Phase 1: Verify substrate
+
+Confirm `.work/CONVENTIONS.md` exists in the project. If not, halt:
+> "No agile-workflow substrate found. Run `/agile-workflow:convert` to bootstrap, then
+> retry."
+
+### Phase 2: Capture the idea
+
+Preserve the user's useful context without turning park into design work:
+- **Slug**: kebab-case `id`, prefixed `idea-` by default (e.g.,
+  `idea-csv-export`, `idea-multi-tenancy`). Use `roadmap-` only when the user
+  explicitly asks to park a roadmap-style or multi-arc capture. Keep it short —
+  2-5 words.
+- **Tags**: only if the user mentioned a clear category (e.g., "park this security
+  thought" → `[security]`). Otherwise leave empty.
+- **Body**: size the capture to the input and situation. A simple idea can be
+  one paragraph. A rich idea can keep bullets, pasted notes, links, referenced
+  files, relevant constraints, or "current situation" context from the active
+  thread. A roadmap-style capture can preserve multiple possible epic/feature/story
+  arcs as raw notes. It is not a binding release roadmap or an active decomposition.
+
+Only include information already supplied by the user or directly necessary to
+make the parked thought intelligible later. You may lightly organize, dedupe, and
+label that context. Do not add new requirements, propose fresh architecture, choose
+kind/stage/parent/dependencies, or decompose the work beyond what the user already
+said — those happen at scope/design time only when asked.
+
+### Phase 3: Write the file
+
+Write to `.work/backlog/<id>.md`:
+
+```yaml
+---
+id: <id>
+created: YYYY-MM-DD     # today's local date (matches the PostToolUse hook)
+updated: YYYY-MM-DD     # same as created at birth; the PostToolUse hook bumps it on every edit
+tags: [<tag>, ...]      # empty array if no clear category
+---
+
+<idea body sized to the capture: one paragraph, bullets, or roadmap-style notes>
+```
+
+`updated` is written equal to `created` so a backlog item carries a reliable
+last-touched signal from birth (the hook is replace-only and cannot insert a
+missing `updated:` line). It stays optional in the backlog contract — a legacy
+item without it is treated as last-touched at `created`.
+
+If a backlog file with the same `id` already exists, append a numeric suffix
+(`idea-csv-export-2`, `roadmap-admin-ux-2`, etc.).
+
+### Phase 4: Commit
+
+```bash
+git add .work/backlog/<id>.md
+git commit -m "park: <id>"
+```
+
+Then return to the prior conversation. Park is a side trip; don't expand on what was
+captured beyond confirming the slug.
+
+## Output
+
+One-line confirmation in conversation:
+> "Parked: `<id>`"
+
+## Guardrails
+
+- Park is a single-stride operation. Do NOT promote to active, do NOT design, do NOT
+  ask about scope, dependencies, or release binding. Those are scope's job.
+- Do NOT proactively add design after invocation. Preserve and lightly organize
+  supplied context, but do not create new plans, requirements, acceptance criteria,
+  or decomposition unless the user explicitly included them in the parked thought.
+- Do NOT compress rich context into a one-paragraph summary when that would lose
+  useful information. Low-friction capture means no extra process, not minimal
+  content at all costs.
+- Do NOT skip the commit. Each park is a cheap, atomic git event so the user can revert
+  individual parks cleanly if needed.
+- Do NOT add the parked item to the conversation's working context — the user wants it
+  out of mind so they can keep working on the current thread.

package/skills/perf-design/SKILL.md

@@ -0,0 +1,427 @@
+---
+name: perf-design
+description: >
+  ALWAYS invoke when the user asks to profile performance, find bottlenecks, optimize code, make
+  something faster, or design a [perf]-tagged feature; do not optimize inline. Discovery mode profiles
+  likely hot paths and emits substrate items per bottleneck. Per-feature mode designs an existing
+  stage:drafting [perf] feature, writes the plan and benchmark scaffolds into the feature body, spawns
+  child stories, and advances drafting to implementing. Uses the hierarchy: algorithmic/data model,
+  I/O, data locality and CPU/cache behavior, language/runtime idioms, then parallelism. Route
+  greenfield work to feature-design and refactors to refactor-design.
+---
+
+# Perf-Design
+
+You diagnose performance bottlenecks via profiling, then design optimized solutions
+following a strict optimization hierarchy. The plan lives in the feature item's body,
+including benchmark scaffolds for the implementation pass.
+
+Use the hierarchy to choose solution shape, and use the profiling taxonomy below
+to choose what to measure. For low-level engines, runtimes, databases, compilers,
+graphics/simulation code, storage/networking code, or any CPU-bound path with
+tight throughput or tail-latency targets, CPU/cache behavior is first-class. If
+you do not collect microarchitecture evidence for that class of work, state why.
+
+## Trigger
+
+The agent picks this skill in two cases:
+- A feature at `stage: drafting` with `tags: [perf, ...]` is ready for design (per-feature mode)
+- The user asks to find perf candidates ("what's slow", "profile the codebase", "find perf issues") (discovery mode)
+
+Common phrases:
+- per-feature: "design the perf optimization for X", "plan the perf work on Y"
+- discovery: "find perf issues", "what's slow here", "profile the codebase"
+
+## Invocation modes
+
+| Invocation | Behavior |
+|---|---|
+| `perf-design` (no arg) / `--all` | **Discovery mode**: detect entry points, pick top 3-5 hot paths, profile, emit items |
+| `perf-design <path>` | Discovery mode scoped to a path |
+| `perf-design <NL scope>` (e.g. "the api layer") | Discovery mode scoped by NL filter |
+| `perf-design <feature-id>` | **Per-feature mode**: design the perf work for an existing `[perf]`-tagged feature at `stage: drafting` |
+| `perf-design --only-questions <id>` / `--only-questions --all` | Question-only alignment pass over `[perf]`-tagged drafting features. Captures answers under `## Design decisions`, does NOT design or advance stage. Requires interactive mode. |
+
+Disambiguation: an arg is treated as a feature id only if
+`.work/active/features/<arg>.md` exists and has `tags: [perf]`. Otherwise
+discovery mode against the arg as path or NL scope.
+
+## Workflow — discovery mode
+
+Use this path for `perf-design`, `--all`, `<path>`, or `<NL scope>`. Goal:
+profile likely hot paths, emit items per bottleneck.
+
+### Phase D1: Resolve scope
+
+- no arg / `--all` → whole codebase
+- `<path>` → that directory or file
+- `<NL scope>` → interpret against the codebase structure; log the interpretation
+
+### Phase D2: Detect entry points and pick top N
+
+Discover candidate entry points: HTTP handlers, CLI commands, public library
+APIs, batch job entrypoints, hot loops with measurable workload. Use Glob and
+Grep against the target scope.
+
+Pick the **top 3-5** entry points most likely to dominate runtime. Heuristics:
+on critical user paths, called per-request or per-event, high call count from
+logs/tests, known historically slow, contain nested loops or I/O.
+
+If confidence is low about which to pick, ask via `structured question tool` (single
+multi-select question). Log the picks.
+
+**Cap the scan.** Never profile every function in the codebase.
+
+### Phase D3: Profile the picks
+
+For each picked entry point, run the existing Phase 3-5 logic (detect &
+research profiling tools, profile, diagnose). Capture top bottleneck per entry
+point.
+
+### Phase D4: Emit items per bottleneck
+
+| Bottleneck shape | Item kind | Stage |
+|---|---|---|
+| Single-site, surgical fix (e.g. eliminate one N+1) | story | `implementing` |
+| Multi-site or needs a design pass / benchmarks | feature | `drafting` (with `[perf]` tag — per-feature mode picks up later) |
+
+Set `gate_origin: perf-design`. Brief = bottleneck location + profiling
+evidence + proposed hierarchy level + probe family.
+
+Commit per batch:
+```bash
+git add .work/active/stories/ .work/active/features/
+git commit -m "perf-design discovery: <N> bottlenecks across <M> entry points"
+```
+
+### Phase D5: Output
+
+In conversation:
+- **Scope**: how the target was interpreted
+- **Entry points profiled**: the picks
+- **Bottlenecks**: count, with top hierarchy levels and probe families
+- **Items emitted**: counts by kind with new ids
+- **Next**: start an autopilot goal to drain, or run
+  `/agile-workflow:perf-design <feature-id>` per emitted feature for the
+  detailed design pass
+
+## Workflow — `--only-questions` mode
+
+Mirrors `feature-design`'s `--only-questions` mode, scoped to `[perf]`-tagged
+drafting features. Iterate over the target set:
+
+1. Read the feature; skip if not `[perf]`-tagged or not at `stage: drafting`
+2. Light ground (foundation docs + AGENTS.md / CLAUDE.md + existing benchmarks)
+3. Surface strategic ambiguities specific to perf (e.g., "what target
+   scenario?", "current vs desired measured throughput?", "target hardware?",
+   "acceptable memory or layout tradeoff for speed?"). Use structured question tool.
+4. Capture answers under `## Design decisions` in the feature body
+5. Do NOT design or advance stage
+6. Commit per feature: `perf-design --only-questions: <id>`
+
+Requires interactive mode; refuse to run under an active autopilot run or goal.
+
+## The optimization hierarchy
+
+Higher levels produce bigger wins with less complexity. Walk top-down for each
+bottleneck.
+
+| Priority | Level | Examples |
+|---|---|---|
+| 1 (highest) | **Algorithmic / data model** | Better data structures, reduced complexity class, eliminated redundant work, changed representation or traversal that reduces work |
+| 2 | **I/O / service boundary** | Batched queries, connection pooling, eliminated N+1, reduced serialization, fewer syscalls |
+| 3 | **Data locality / microarchitecture** | Contiguous access, hot/cold splits, AoS vs SoA, fewer pointer hops, cache/TLB locality, branch predictability, SIMD/vectorization, false-sharing fixes |
+| 4 | **Language / runtime idioms** | Pre-allocation, avoiding copies/boxing, string builders, fewer temporary objects, lower GC pressure, monomorphization/devirtualization when measured |
+| 5 (lowest) | **Parallelism** | Worker pools, async pipelines, concurrent data structures, sharding to reduce contention |
+
+**Exception**: Parallelism moves up when the bottleneck is *inherently parallel* —
+processing N independent requests sequentially, or a map operation over independent
+items. In those cases, parallelism IS the algorithmic fix.
+
+**Data-layout rule**: if changing layout changes the work model or traversal shape,
+treat it as level 1. If the algorithm stays the same but the hot path is bound by
+cache misses, TLB misses, branch misses, vectorization limits, or cache-line
+contention, treat it as level 3.
+
+## Profiling taxonomy
+
+Do not run every profiler. Pick probes that match the symptom, workload, and
+runtime. Record skipped high-value probes when the target is low-level or
+CPU-bound.
+
+| Probe family | Finds | Typical evidence |
+|---|---|---|
+| **Workload baseline** | Real throughput/latency target, p50/p95/p99, warmup effects, regression budget | benchmark timings, load-test output, production trace/metric excerpts |
+| **On-CPU time** | Hot functions, call paths, inefficient loops | CPU samples, wall/CPU flamegraphs, cumulative time |
+| **Memory allocation / GC** | Allocation rate, retained heap, GC pauses, allocator overhead | allocs/op, bytes/op, heap profile, GC traces, RSS growth |
+| **I/O and serialization** | Slow DB/network/disk calls, redundant round-trips, syscall overhead | traces/spans, query logs, syscall profiles, bytes transferred |
+| **Off-CPU / synchronization** | Blocking, lock contention, scheduler delay, queueing | block/mutex profiles, off-CPU flamegraphs, run queue, context switches |
+| **Microarchitecture** | IPC/CPI loss, cache/TLB misses, branch misses, frontend/backend stalls, vectorization limits | hardware counters, cache/branch profiles, compiler vectorization reports, instruction throughput analysis |
+| **Cache-line / NUMA contention** | False sharing, remote memory access, cross-core cache bouncing | c2c/cache-line reports, remote vs local access counters, per-core contention evidence |
+
+For low-level high-performance systems, include a microarchitecture pass when
+the profile is CPU-bound: at minimum cycles/instructions/IPC, cache/LLC or TLB
+misses, and branch misses when tooling permits. Add false-sharing/NUMA probes
+when threads mutate adjacent or shared state.
+
+## Workflow — per-feature mode
+
+### Phase 1: Read the feature item
+
+Read `.work/active/features/<id>.md`. Confirm:
+- `kind: feature`
+- `stage: drafting`
+- `tags` includes `perf`
+
+The brief should describe the perf problem and target. If it's vague:
+- Autopilot mode: profile the hottest identifiable path, set a "2x current"
+  default target, log under `## Inferred targets` in the body. Halt only if
+  there's no measurable scenario at all (no entry point matching the brief).
+- Otherwise: ask the user for target scenario, current measured performance,
+  desired performance.
+
+### Phase 2: Ground yourself
+
+The principles skill auto-loads. Read:
+- `docs/VISION.md`, `docs/SPEC.md` (perf targets may be specified)
+- `AGENTS.md` / `CLAUDE.md`
+- `.agents/rules/*.md` (if present) — the project's force-loaded agent rules
+  (tag semantics, test integrity, review policy)
+- Existing benchmarks (search for benchmark files, perf tests, load tests)
+- Existing test suite (so benchmarks follow the same patterns)
+- Source code under investigation — read the target code thoroughly before profiling
+
+### Phase 3: Detect & research profiling tools
+
+1. Detect language and runtime from the project's source files and build config
+2. Spawn a research sub-agent:
+   - Use the host's generic/general-purpose subagent prompted with the explorer
+     capsule from `../principles/references/subagents.md`, at medium reasoning
+     for known stacks.
+   - Use high reasoning for unfamiliar runtimes or deeper investigations, and
+     strongest reviewer reasoning only for broad, high-risk perf redesigns.
+   - If no generic subagent adapter is available, keep the same host-local
+     research fallback.
+   Brief it:
+   "Find the recommended profiling tools for <language/runtime>. Return: CPU
+   profiler, memory/allocation profiler, I/O/tracing tool, lock/off-CPU profiler,
+   flamegraph workflow, and hardware-counter/cache/branch tools for CPU-bound or
+   low-level code. Include ecosystem-specific gotchas. Verify from current docs -
+   do not trust training data."
+3. Read the results before proceeding
+
+### Phase 4: Profile
+
+Run profiling using the researched tools via Bash.
+
+1. **Workload baseline**: capture current throughput/latency with representative
+   input. Include warmup, input size, machine/runtime details, and the exact run
+   command when they affect repeatability.
+2. **CPU/latency**: profile the target code path. For a function: write a driver
+   script. For a server: use existing load tests or write a minimal one.
+3. **Memory**: track allocation counts and sizes; identify GC/allocator pressure
+   if applicable.
+4. **I/O / serialization**: inspect traces, query logs, syscall/network/disk
+   profiles, or spans when the hot path crosses process or storage boundaries.
+5. **Off-CPU / synchronization**: profile blocking time, mutexes, channels,
+   scheduler delay, and queueing when wall time exceeds on-CPU time or concurrent
+   work is involved.
+6. **Microarchitecture**: for CPU-bound or low-level high-perf paths, collect
+   counters for cycles, instructions, IPC/CPI, cache/LLC/TLB misses, and branch
+   misses when tooling permits. Use cache/branch profilers, compiler
+   vectorization reports, or instruction-throughput analyzers when they fit.
+7. **Cache-line / NUMA contention**: for multi-threaded hot paths, check false
+   sharing, cache-line bouncing, remote memory, and per-core contention when
+   shared or adjacent mutable state appears in the profile.
+8. **Flamegraphs** if the ecosystem supports them.
+9. **Save raw output** to a temp file for reference.
+
+### Phase 5: Diagnose
+
+Analyze the profile to identify top bottlenecks.
+
+1. **Rank by impact** — sort hot spots by cumulative time or allocation volume
+2. **Categorize** each bottleneck by hierarchy level and probe family:
+   - Wrong complexity class, redundant work, or representation forces excess work? -> Algorithmic / data model
+   - Waiting on I/O, redundant calls, syscalls, or unnecessary serialization? -> I/O / service boundary
+   - CPU-bound with poor cache/TLB locality, pointer chasing, branch misses, vectorization limits, or false sharing? -> Data locality / microarchitecture
+   - Excess allocations, copies, boxing, temporary objects, GC pressure, or inefficient runtime construct? -> Language / runtime idiom
+   - Inherently parallel work being done sequentially, or contention solved by ownership/sharding? -> Parallelism
+3. **Identify the top 3-5 bottlenecks**. Don't try to fix everything.
+
+For each bottleneck, note:
+- File and function/method
+- Profiling evidence (time %, allocation count, call count, IPC/cache/branch
+  counters, lock/off-CPU time, trace span, etc. as applicable)
+- Current complexity class (if relevant)
+- Why it's slow (root cause, not symptom)
+
+### Phase 6: Design solutions
+
+For each bottleneck, walk the hierarchy top-down:
+
+1. **Algorithmic / data-model fix?** Better data structure, reduced work,
+   eliminated redundancy, changed layout/traversal that reduces the amount of
+   work?
+   If yes → design it. Stop here.
+2. **I/O fix?** Batching, pooling, eliminating round-trips, reducing serialization?
+   If yes → design it. Stop here.
+3. **Data-locality / microarchitecture fix?** Contiguous access, hot/cold split,
+   AoS/SoA change, fewer pointer hops, cache/TLB locality, predictable branches,
+   SIMD/vectorization, cache-line padding/alignment, NUMA locality, or reduced
+   false sharing?
+   If yes → design it. Stop here.
+4. **Language / runtime idiom fix?** Pre-allocation, avoiding copies/boxing,
+   fewer temporary objects, lower GC/allocator pressure, devirtualization, or
+   simpler constructs?
+   If yes → design it. Stop here.
+5. **Parallelism?** Or is the work inherently parallel (algorithmic)?
+   If yes → design it with explicit justification for why higher levels don't apply.
+
+For each solution:
+- Hierarchy level + probe family + why higher levels don't apply (skip this for level 1)
+- Expected improvement (quantified: "O(n²) → O(n log n)" or "eliminates N round-trips")
+- Expected metric movement (wall time, p99, allocations/op, cycles/op, IPC,
+  cache-miss rate, branch-miss rate, lock wait, bytes transferred)
+- Exact file paths and function signatures
+- Implementation notes for non-obvious logic
+- Risk assessment (does this change behavior? thread safety concerns?)
+
+### Phase 7: Scaffold benchmarks
+
+Write benchmark code that measures before/after.
+
+1. Determine benchmark location per project conventions. Adjacent to code under test
+   if no standard location exists.
+2. Write **before benchmarks** (baseline) using the language's standard benchmarking
+   framework (`testing.B` in Go, `pytest-benchmark` in Python, `vitest bench` in JS,
+   etc.).
+3. Write **after benchmark stubs** with comments indicating expected targets.
+4. Include representative input data — must exercise the actual hot path.
+5. For low-level CPU-bound optimizations, include hardware-counter or
+   cache/branch measurements in the benchmark command when the project tooling
+   supports them.
+
+### Phase 8: Spawn child stories
+
+Each optimization that warrants its own implementation pass becomes a child story:
+- `.work/active/stories/<feature-id>-opt-<N>.md`
+- `kind: story`, `stage: implementing`, `parent: <feature-id>`,
+  `tags: [perf]`, `depends_on: [...]` (in order — usually higher-impact first)
+- Body: the optimization's design + benchmark expectations
+
+For trivial single-site optimizations, skip child stories.
+
+### Phase 9: Write plan INTO feature body
+
+Append to the feature file:
+
+```markdown
+## Perf Overview
+<what was profiled, key findings, summary of proposed optimizations>
+
+## Profiling Summary
+<top hot spots with data, allocation patterns, flamegraph highlights>
+
+## Optimization Plan
+
+### Optimization 1: <name>
+**Hierarchy Level**: Algorithmic / Data Model / I/O / Data Locality / Microarchitecture / Runtime Idiom / Parallelism
+**Probe Family**: <CPU / memory / I/O / off-CPU / microarchitecture / cache-line / NUMA>
+**Bottleneck**: <what's slow and why — cite profiling data>
+**Expected Metric Movement**: <wall time, p99, allocations/op, cycles/op, cache misses, branch misses, lock wait, etc.>
+**Why higher levels don't apply**: <skip for algorithmic-level fixes>
+**Story**: `<story-id>` (if spawned)
+
+#### Implementation Units
+
+##### Unit 1.1: <name>
+**File**: `src/path/to/file.ext`
+
+\`\`\`<lang>
+// Exact interfaces, types, signatures
+\`\`\`
+
+**Implementation Notes**:
+- <key detail>
+
+**Acceptance Criteria**:
+- [ ] Benchmark shows improvement of <X>
+- [ ] Existing tests pass
+- [ ] <specific behavioral criterion>
+
+---
+
+## Benchmarks
+**Location**: <benchmark file path>
+**Run command**: <command>
+**Baseline targets**: <current measured>
+**Expected targets**: <post-optimization>
+**Counter targets**: <optional cycles/op, IPC, cache/branch miss rate, allocations/op>
+
+## Implementation Order
+1. <highest impact, lowest risk first>
+2. <next>
+```
+
+### Phase 10: Advance stage and commit
+
+1. Update feature frontmatter: `stage: drafting → implementing`.
+2. Commit (include the benchmark scaffolds):
+   ```bash
+   git add .work/active/features/<id>.md .work/active/stories/<feature-id>-opt-*.md <benchmark-files>
+   git commit -m "perf-design: <feature-id> (<N> optimizations)"
+   ```
+
+## Output
+
+In conversation:
+- **Designed**: `<feature-id>` advanced to `stage: implementing`
+- **Top bottlenecks**: list with hierarchy level and probe family
+- **Optimizations**: list ordered by impact
+- **Benchmarks**: location and run command
+- **Next**: `/agile-workflow:implement <story-id>` per optimization, or
+  `/agile-workflow:implement-orchestrator <feature-id>` for parallel agents
+
+## Common traps
+
+- Reach for parallelism only after exhausting algorithmic, I/O, data-locality,
+  and language/runtime solutions — parallelism adds complexity, and higher-level
+  fixes often eliminate the bottleneck entirely
+- Design solutions from profiling data, not intuition — gut feelings about
+  bottlenecks are frequently wrong
+- **Focus effort on the hot path** — optimizing cold code wastes time for
+  unmeasurable gains. If a function takes 0.1% of total time, a 10x speedup is
+  invisible.
+- Treat caching as a band-aid, not a fix — caching hides the real problem and
+  adds invalidation complexity. Only propose caching when the underlying work
+  is genuinely irreducible.
+- Profile memory alongside CPU — GC pressure and allocation overhead are real
+  bottlenecks that CPU profiles miss
+- Do not skip CPU/cache evidence for low-level CPU-bound systems. If hardware
+  counters or cache/branch tools are unavailable, say what blocked them and use
+  the nearest substitute.
+- Treat microbenchmarks as evidence, not proof. Validate hot-path wins against
+  representative end-to-end workload, and control obvious noise: warmup, input
+  size, CPU frequency, debug builds, logging, and background load.
+- Beware pointer chasing, branch unpredictability, cache-line bouncing, and NUMA
+  effects in concurrent low-level code. These often look like "CPU time" until
+  hardware counters or cache-line tools separate the cause.
+- Research the ecosystem's profiling tools first — they vary dramatically and
+  using the wrong one wastes cycles
+
+## Guardrails
+
+- Reach for parallelism only after exhausting higher levels — parallelism adds
+  complexity, and algorithmic/I/O fixes often eliminate the bottleneck entirely
+- Design from profiling data, not intuition. Gut feelings are frequently wrong.
+- Treat caching as a band-aid, not a fix. Caching hides the real problem and adds
+  invalidation complexity. Only propose caching when the underlying work is genuinely
+  irreducible.
+- Profile memory alongside CPU. GC pressure and allocation overhead are real
+  bottlenecks that CPU profiles miss.
+- For low-level CPU-bound work, include CPU/cache and branch evidence or record
+  why it was not available.
+- Research the ecosystem's profiling tools first. Don't trust training data for
+  fast-moving tooling.
+- The plan lives in the feature's body. NEVER create `docs/designs/perf-<name>.md`.