05 Learn

Learn

Use this skill after solving a problem so the repository gains a reusable learning in docs/solutions/.

See shared pipeline instructions for model routing and pipeline behavior.

Necessity gate (decide FIRST)

Before writing anything, decide whether this learning is worth preserving. Most solved problems are NOT worth a solution artifact. Silence is acceptable; noise is not.

Worth preserving (ALL must hold)

1. Non-trivial — the solution required real investigation, not a one-glance fix.
2. Reusable — the root cause or fix pattern could recur in this or another project.
3. Not already documented — the knowledge is not trivially findable in framework docs, the codebase, a prior solution artifact, or a commit message.

Not worth preserving (any ONE is disqualifying)

• One-off — a typo, a rename, a personal-environment quirk unlikely to recur.
• Common knowledge — standard framework usage, language basics, or anything a competent practitioner would know or find in official docs in under a minute.
• Already captured — the learning is fully expressed in the code, its tests, a commit message, or an existing docs/solutions/ artifact.
• Trivial refactor — formatting, import sorting, or mechanical changes with no insight.
• No root cause insight — the fix worked but you cannot explain why it worked; without the "why", the artifact will not help future readers.

Outcome

• If not worth preserving: respond concisely (e.g. "No solution artifact needed: ") and stop. Do not create a file.
• If worth preserving: proceed to Core rules below.

Core rules

• Every solution MUST include YAML frontmatter per references/solution-schema.yaml (title, category, severity, tags, applies_when).
• Use references/category-map.md to map the problem to the correct solution category.
• Check for overlap with nearby solution docs before creating a new artifact.
• Use references/overlap-rules.md to decide whether to create, update, consolidate, or retire.
• Before writing, scan existing artifacts yourself for recurring patterns — read the nearby solution docs and note repeated themes (no dedicated tool needed).
• Structure the document with assets/solution-template.md.
• Determine storage level:
  • Project-specific → {project-root}/docs/solutions/ (only relevant to current project)
  • Cross-project (global) → ~/.pi/agent/docs/solutions/ (applicable to any project)
  • Default to global when uncertain.
• Out-of-scope branch: if the request was rejected or already implemented, write to docs/out-of-scope/ (template: assets/out-of-scope-template.md, convention: assets/out-of-scope-convention.md) instead of docs/solutions/.
• Make the result useful to future 02-plan and 04-review runs via the search strategy in references/solution-search-strategy.md.
• If this phase's plan still sits in docs/plans/ with work complete (path skipped 04-review), flip its Status header to done and move it to docs/plans/archive/ — same Close semantics as 04-review step 6.

Workflow

1. Identify the recently solved problem or learning.
2. Scan docs/solutions/ for related artifacts and recurring patterns, and perform an overlap check.
3. Choose the correct category using references/category-map.md.
4. Write or update the solution artifact under docs/solutions/<category>/.
5. Mention how future 02-plan and 04-review runs should benefit from the new learning.
6. Include 🧠 Context Status (health, handoff path, active files, new-session recommendation) for workflow closure.
7. Save/mention handoff-lite path under .context/compound-engineering/handoffs/ using the shared Handoff-lite template in skills/references/pipeline-config.md.

Before finishing this skill, apply the completion checklist in shared pipeline instructions.