This skill can run after any phase or standalone session. It compounds the agent’s effectiveness over time.

Please provide the task identifier, or I’ll try to find the current task from context.

You can find active tasks in ./apex/tasks/ or run with: /apex:compound [identifier] Load task file and begin knowledge capture.

Search past task files for similar learnings

Grep: “[keywords]” in apex/tasks// Grep: “.[keywords]” in apex/tasks/.md Grep: “.[keywords]” in apex/tasks/.md Grep: “.[keywords]” in apex/tasks/*.md

</search-strategy>

<if-similar-found>
Display to user:

Found potentially related learnings:

1. [task-id]: “[Brief description of learning]”
2. [task-id]: “[Brief description of learning]”

Continue documenting? (These will be linked as related)

• Yes – Continue (will add to related_tasks)
• Skip – This is duplicate, don’t document

Wait for user response before proceeding.
</if-similar-found>

<if-no-similar>
Proceed directly to step 3.
</if-no-similar>
</step>

<step id="3" title="Gather learnings from session">
<instructions>
Review the task file and conversation to identify:

**Problems Encountered**:
- What broke or didn't work as expected?
- What symptoms were observed?
- What was the root cause?
- How was it fixed?
- How can it be prevented in future?

**Decisions Made**:
- What architectural or implementation choices were made?
- What alternatives were considered?
- Why was this choice made over others?

**Gotchas Discovered**:
- What surprised you or was counterintuitive?
- What looked like X but actually was Y?
- What documentation was misleading or missing?
</instructions>

<gathering-prompts>
Ask yourself:
1. "What would have saved time if I knew it at the start?"
2. "What mistake did we make that future agents should avoid?"
3. "What decision required significant thought that future agents can reuse?"
4. "What behavior was unexpected or undocumented?"
</gathering-prompts>

<minimum-threshold>
Only document if there's at least ONE meaningful learning.
If the task was trivial with nothing surprising, say:
"No significant learnings to capture from this session."
</minimum-threshold>
</step>

<step id="4" title="Structure learnings">
<format>
```xml
<future-agent-notes>
  <timestamp>[ISO timestamp]</timestamp>

  <problems>
    <problem>
      <what>[Clear description of the problem]</what>
      <symptoms>
        - [Observable sign 1]
        - [Observable sign 2]
      </symptoms>
      <root-cause>[Why it happened]</root-cause>
      <solution>[What fixed it]</solution>
      <prevention>[How to avoid in future]</prevention>
    </problem>
  </problems>

  <decisions>
    <decision>
      <choice>[What we chose]</choice>
      <alternatives>[What we considered]</alternatives>
      <rationale>[Why this choice - be specific]</rationale>
    </decision>
  </decisions>

  <gotchas>
    <gotcha>[Surprising thing - be specific and actionable]</gotcha>
  </gotchas>
</future-agent-notes>

Frontmatter update (if related tasks found):

---
# ... existing frontmatter ...
related_tasks: [task-id-1, task-id-2]
---

Problems (N):

• [Brief summary of each]

Decisions (N):

• [Brief summary of each]

Gotchas (N):

• [Brief summary of each]

Related tasks linked: [list or “none”]

</confirmation>
</step>

<step id="6" title="Offer promotion to AGENTS.md">
<purpose>
Critical learnings should be "always loaded" context in AGENTS.md.
</purpose>

<promotion-prompt>

Promote any to AGENTS.md? (These become “always loaded” context)

1. [Problem] [Brief description]
2. [Decision] [Brief description]
3. [Gotcha] [Brief description] N. None – done

Select (numbers comma-separated, or N for none):

</promotion-prompt>

<selection-handling>
- If "N" or "none": Skip to final step
- If numbers selected: Proceed to promotion
</selection-handling>
</step>

<step id="7" title="Promote to AGENTS.md">
<instructions>
1. Read AGENTS.md fully
2. Find `## Learnings` section (create at end if doesn't exist)
3. Check for duplicates (don't add if similar already exists)
4. Append selected items in condensed format
5. Write updated AGENTS.md
</instructions>

<promotion-format>
```markdown
## Learnings

<!-- Auto-generated by /apex:compound. Do not edit directly. -->

### Problems

- **[Short title]** - [1-2 sentence description with actionable prevention]. (from [task-id], [date])

### Decisions

- **[Choice made]** - [1-2 sentence rationale]. (from [task-id], [date])

### Gotchas

- **[Short title]** - [1-2 sentence explanation]. (from [task-id], [date])

Task: [identifier]

Learnings documented:

• Problems: [N]
• Decisions: [N]
• Gotchas: [N]

Related tasks: [list or “none”] Promoted to AGENTS.md: [list or “none”]

These learnings will be surfaced by learnings-researcher in future /apex:research runs.