adragomir/capture-learnings

Capture Learnings

Turn non-obvious discoveries into the smallest durable artifact so future work is faster and safer.

When to use this skill

Two triggers:

1. At the end of every task (automatic gate)

   • Apply Gate
   • If it matches: persist/update the highest-leverage artifact(s) and say what you changed
   • If it doesn't: output Capture Learnings: skipped (<reason>)

2. When explicitly asked (direct capture)

   • User says "capture," "record," "document," "note" a convention/pattern in the repo
   • Skip the gate—persist what was requested directly
   • Examples: "capture that we always commit to main," "record this workflow," "document this convention"

Gate (persist only if ≥1 is true)

• High cost of rediscovery (took real time / >1 failed attempt)
• High blast radius (prod bugs, security issues, data loss)
• High frequency (likely again within ~3 future tasks)
• Low discoverability (no obvious keyword/entrypoint; you’d have to “already know”)
• Stale guidance exists (wrong/expired/contradictory)
• While using an existing doc/skill/AGENTS.md you found gaps worth fixing

If none apply: Capture Learnings: skipped (too task-specific / already discoverable).

Choose the artifact (routing rules)

Prefer changing reality over documenting it:

1. Code/config/tests/CI: make it true (types/tests/lint/CI/scripts).

2. Nearest subtree AGENTS.md: a rule/gotcha you must follow while working in a specific part of the tree.

   • AGENTS.md is canonical + portable for all agents (not just Claude).
   • Mandatory for Claude Code (loads CLAUDE.md, not AGENTS.md): same-dir CLAUDE.md containing @AGENTS.md.
   • Style: telegraph; noun-phrases ok; drop filler/grammar; min tokens.
   • Do not dump subtree rules into the project root.
   • If unsure where a rule belongs:
     • Run fd AGENTS.md <subtree-root> (or fd AGENTS.md if unsure) and pick the closest governing file.
     • If the project has multiple AGENTS.md files: update the closest one that governs the files you touched.
     • If none exists in the relevant subtree: create both AGENTS.md (rules) + CLAUDE.md (@AGENTS.md) in that subtree.
     • Project root AGENTS.md: last resort; only project-wide invariants.
     • Scope test: would this be wrong/irrelevant for >50% of edits in the project? If yes, it does not belong in root.
   • Prefer pointing to an existing “good example” file/path over describing abstract patterns.

3. Project-local skill (<project>/.pi/skills/<name>/SKILL.md): a repeatable agent workflow.

   • Use when it’s 3+ steps, easy to mess up, and has clear verification.
   • Do not create a skill for a single rule (that belongs in AGENTS.md).

4. docs/: only for durable artifacts like feature specs, agent TODOs, and developer docs.

   • docs/ is not a dumping ground for generic background/rationale.

Quick checks

• “I must remember a rule while editing files under X/**” → nearest X/**/AGENTS.md (+ same-dir CLAUDE.md with @AGENTS.md)
• “I must run a playbook and verify it worked” → project-local skill in .pi/skills/
• “I need a living spec/todo/runbook that will be referenced” → docs/ (update an existing doc if possible)

Hard constraints (prevents low-signal artifacts)

docs/ gate (avoid junk)

Write to docs/ only if at least one is true:

• The task explicitly asked for a spec/todo/doc.
• The information is a structured artifact you’ll reuse (spec/checklist/runbook), not “what I learned”.
• There is a clear existing place to put it (an existing file/section).

If you do write/update docs/:

• Prefer updating an existing doc over creating a new doc.
• Do not add long narrative sections (“Architecture”, “Rationale”, “Troubleshooting”) unless explicitly requested.

Skills: local-first + pi grounding

Skills are often misunderstood; keep them concrete and procedural.

Local-first rule:

• Default to project-local skills in <project>/.pi/skills/.
• Only create a global skill if it is truly cross-project and contains no project-specific paths/commands.

Before creating/updating a skill (or hooks/tools/providers/themes):

• Read the pi docs and follow cross-references:
  • /path/to/@mariozechner/pi-coding-agent/docs/skills.md
• Read ~2 existing skills in the same scope (project-local vs global) and match their conventions.

Scope (where it lives)

• Project-specific workflow → <project>/.pi/skills/<name>/
• Cross-project/personal habit → ~/.pi/agent/skills/<name>/
• Cross-project agent rules/workflow → ~/.pi/agent/AGENTS.md (don't create CLAUDE.md here)
• Subtree-specific rules/workflow → nearest relevant AGENTS.md (+ same-dir CLAUDE.md with @AGENTS.md)
• Project-wide rules/workflow → project root AGENTS.md (+ same-dir CLAUDE.md with @AGENTS.md)

Prefer updating an existing artifact over creating a new one; avoid duplicates.

What to persist

• Non-obvious commands/paths/flags/env vars that matter
• Conventions/patterns you had to infer by reading code
• Gotchas that caused failures/iteration (tests, tooling, auth, permissions)
• Constraints/tradeoffs that shape future changes

Avoid persisting

Do not persist:

• Generic best practices
• Facts already obvious from the codebase
• Task logs (“what I just did”)
• One-off reminders/TODOs outside the agreed docs/ TODO workflow

Quality bar

• Tight and high-signal
• Prefer copy/pastable commands and concrete paths over prose
• Never store secrets (tokens, credentials, private URLs)
• Treat staleness as a bug: delete/update invalid guidance so there’s one canonical source