pm-learn git:20260729.8dd5ad0A

Immutable. This exact content never changes and is served at /api/v1/blob/7e10730e8ef85563.

---
name: pm-learn
description: "Auto-extract repeatable patterns, decisions, and cost outliers from the current session and append to .great-pm/lessons.md. Promotes ≥3-occurrence patterns to ~/.great-pm/decisions.md. Runs continuous-learner."
---

## Codex host binding

- Treat references to Claude slash workflows as the equivalently named Codex skill.
- Before delegating to any specialist, read the `great-pm-runtime` skill and the selected packaged role file.
- Treat "invoke", "assign", "delegate", "spawn", and source Agent-tool instructions as a required Codex `spawn_agent` call with that role and a bounded assignment.
- Set `task_name` to the exact canonical role name from the selected role file; never shorten, paraphrase, or invent specialist names.
- Store every returned agent identifier. Never call a wait tool until a spawn has returned an identifier, and wait only on identifiers returned by successful spawns.
- If `spawn_agent` is unavailable or a spawn fails, report BLOCKED; do not impersonate the specialist or wait on an empty agent set.
- Resolve bundled paths from the installed GreatPM plugin root.
- Ignore Claude-only model aliases, colors, turn limits, and tool allowlists.
- Preserve GreatPM human gates, governance, state, and reporting contracts.


You are the great-pm `$pm-learn` command. Capture session learnings without
requiring a full `$pm-save`.

## Parse arguments

- `--dry-run` → continuous-learner produces the lessons block but does NOT
  write it to disk. Print preview only.
- (no flag) → write to `.great-pm/lessons.md` and promote ≥3-occurrence
  patterns to `~/.great-pm/decisions.md`.

## Pre-flight

```bash
echo "cwd=$(pwd)"
mkdir -p .great-pm
ls .great-pm/lessons.md 2>/dev/null && echo "LESSONS_OK" || echo "FIRST_RUN"
ls .great-pm/.learn-pending 2>/dev/null && echo "PENDING_MARKER" || echo "NO_MARKER"
```

If `PENDING_MARKER` exists → this is the recommended path (SessionEnd hook
flagged something worth capturing).

## Operating procedure

0. **Step 0 — refine the user's query** (transparent Mode B). Invoke
   `query-refiner-pm` with `$ARGUMENTS`. The refiner returns:
   ```
   You typed:  <original>

   Refined to: <refined brief>

   What changed: <one line>

   Proceeding with refined. Reply "use original" to override.
   ```
   Use the **refined** version as the brief for subsequent steps UNLESS
   the user replies "use original". Log the refinement to
   `.great-pm/refinements/$(date +%Y-%m-%d).log`. This wiring is
   universal across great-pm commands per the gate-policy: explicit
   discipline — you make the user's leverage visible while preserving
   their ability to override.

1. Spawn `continuous-learner` as a subagent with:
   - Mode: `auto-extract` (no manual prompt).
   - Read the session history available to you.
   - `--dry-run` flag if set.

2. The agent identifies:
   - Repeatable patterns (≥2 occurrences in this session).
   - Decisions worth promoting (architectural, governance, naming).
   - Cost outliers (long-running agent invocations, repeated tool failures).

3. Output format (appended to `.great-pm/lessons.md`):
   ```
   ## <YYYY-MM-DD HH:MM> session
   - pattern: <one-line>  (count: N)
   - decision: <one-line>  (rationale: <one-line>)
   - cost outlier: <one-line>
   ```

4. If any pattern hits its 3rd occurrence in `lessons.md`, promote it to
   `~/.great-pm/decisions.md` with a back-reference to the 3 sources.

5. Clear `.great-pm/.learn-pending` if it exists.

## Reporting

- **DONE**: `DONE: $pm-learn captured <P> patterns, <D> decisions, <C> cost outliers. Promoted <M> to ~/.great-pm/decisions.md.`
- **DRY-RUN**: `DRY-RUN: would capture <P>/<D>/<C> — preview above.`
- **BLOCKED**: `BLOCKED: continuous-learner failed.` tried + failed_because + need.

## Notes

- This is the lightweight version. `$pm-save` is the full end-of-session
  hand-off (session log + status + lessons + open gates).
- Run `$pm-learn` mid-session whenever you notice the model just learned
  something worth remembering.