@codyswann/lisa 2.9.1 → 2.10.1

package/plugins/lisa/skills/debrief/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: debrief
+description: "Run the Debrief flow over a shipped initiative. Input: a PRD URL (Notion / Confluence / Linear / GitHub Issue / file), a JIRA epic key, or a GitHub epic issue URL. Output: a triage-ready learnings document covering every work item in the initiative — edge cases, gotchas, process friction, tooling gaps, convention drift — each with structured evidence and a human-disposition field. Persistence is deferred to lisa:debrief-apply."
+allowed-tools: ["Skill", "ToolSearch", "TeamCreate", "Bash", "Read", "Glob", "Grep"]
+---
+
+# Debrief: $ARGUMENTS
+
+Walk the original Plan for `$ARGUMENTS`, mine the completed work items and their PRs, and produce a triage-ready learnings document for human review.
+
+## Orchestration: agent team
+
+If you are NOT already operating inside an agent team (no prior `TeamCreate` in this session, not spawned via `Agent` with `team_name`), the very first thing you do is create the team. Two tool calls only, in this exact order:
+
+1. `ToolSearch` with `query: "select:TeamCreate"` — `TeamCreate` is a deferred tool whose schema must be loaded before it can be invoked. A cold call returns `InputValidationError` and tempts a fallback to direct `Agent` calls, which bypasses the team.
+2. `TeamCreate` — actually create the team.
+
+Until `TeamCreate` returns successfully, do NOT call any of: `Agent`, `TaskCreate`, `Skill`, MCP tools (Atlassian / Linear / GitHub / Notion), `Read`, `Write`, `Edit`, `Bash`, `Grep`, `Glob`. Resolving the work-item set, fetching tickets, walking PRs — all of those are tasks for the team you are about to create, not for the lead session before the team exists.
+
+If you ARE already inside an agent team (e.g., a teammate invoked this skill via the Skill tool), do NOT call `TeamCreate` — the harness rejects double-creates. Continue within the existing team.
+
+## Input
+
+`$ARGUMENTS` is one of:
+
+| Input shape | Resolution |
+|-------------|------------|
+| Notion / Confluence / Linear / GitHub Issue PRD URL | Fetch the PRD; read its `## Tickets` (or equivalent) back-link section written by the Plan flow |
+| File path to a PRD markdown | Read the file; parse its `## Tickets` section |
+| JIRA epic key (e.g. `SE-1234`) or epic URL | Fetch the epic; list its child issues (Stories, Tasks, Bugs) |
+| GitHub epic issue URL or `<org>/<repo>#<n>` | Fetch the epic issue; list its sub-issues / linked items |
+
+If the PRD has no `## Tickets` section AND the input is not an epic, stop and report — the Plan flow's PRD back-link step (`lisa:prd-backlink`) was likely skipped. Suggest re-running Plan to populate the section, or pass the epic key directly.
+
+## Gate
+
+Run before mining begins:
+
+1. **All work items terminal.** Every linked work item must be in a terminal state (Done / Closed / Cancelled equivalent for the tracker). If any item is still open, stop and list the unfinished items — Debrief is post-shipping by definition.
+2. **PR coverage.** Every Done item that was implementable (Story / Task / Bug; not Spike) must have at least one merged PR linked. Items missing a PR are recorded as **anomalies** to surface in the report rather than silently excluded — a Done item with no PR is itself a learning ("how did this ship?").
+3. **Headless safety.** In headless / `-p` / scheduled mode, do not block on missing input — fail fast with a clear error listing what was needed.
+
+## Flow
+
+Execute the **Debrief** flow as defined in the `intent-routing` rule (loaded via the lisa plugin). The rule contains the canonical step sequence (gate, mining, synthesis, output, hand-off). This skill does NOT restate flow steps — change them in the rule, propagate everywhere.
+
+The flow's mining step runs `tracker-mining-specialist` and `pr-mining-specialist` in parallel as separate tasks within the team. Both must complete before `learnings-synthesizer` runs. Express this with `blockedBy` so the synthesizer task is automatically gated on the two mining tasks.
+
+## Exhaustiveness expectation
+
+Debrief is deliberately exhaustive — the human, not the agent, decides what is worth keeping. Specialists should err toward surfacing more candidates, not fewer. A candidate that the synthesizer rates low confidence is still a row in the triage doc; only outright duplicates are dropped.
+
+## Output
+
+A markdown triage document at `./debrief/<initiative-slug>-<YYYY-MM-DD>.md` (or wherever the project's debrief output directory is configured) containing:
+
+1. **Header** — initiative name, source PRD/epic link, work-item count, PR count, generation date, gate results.
+2. **Anomalies** — work items missing PRs, items with abnormal status-transition timing, PRs with no review comments at all (signal-of-absence is a learning), etc.
+3. **Candidate learnings** — one row per candidate, grouped by category (Edge case / Recurring gotcha / Process friction / Tooling gap / Convention drift). Each row has:
+   - `Summary` — one sentence
+   - `Category`
+   - `Evidence` — links to the source ticket comment / PR comment / commit / test file (multiple allowed)
+   - `Recommended persistence destination` — the agent's best guess for where this should land if accepted (e.g., "Edge Case Brainstorm checklist → Navigation & URL state", "PROJECT_RULES.md", "memory: project_*.md", "new tooling-gap ticket")
+   - `Disposition` — empty checkbox-style field the human will fill: `[ ] Accept` / `[ ] Reject` / `[ ] Defer` plus a free-text reason
+4. **Source map** — appendix listing every work item and PR walked, so the human can verify completeness.
+
+The skill's terminal output is the path to the triage document and a one-line summary of counts per category. Persistence does not happen here — that is `lisa:debrief-apply`'s job.
+
+## Hand-off
+
+After producing the triage document, print:
+
+```text
+Triage document written to: <path>
+Counts: <n> edge cases, <n> gotchas, <n> friction, <n> tooling gaps, <n> convention drift; <n> anomalies
+Next: human triage. When done, run `/lisa:debrief:apply <path>` to persist accepted learnings.
+```
+
+Then stop. Debrief never persists learnings on its own.

package/plugins/lisa/skills/debrief-apply/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: debrief-apply
+description: "Apply human-marked dispositions from a Debrief triage document. Reads the triage doc produced by lisa:debrief, parses each row's disposition (Accept / Reject / Defer), and routes Accepted items to their persistence destination. Deterministic and idempotent — safe to re-run if dispositions are added incrementally."
+allowed-tools: ["Skill", "Bash", "Read", "Edit", "Write", "Glob", "Grep"]
+---
+
+# Debrief Apply: $ARGUMENTS
+
+Read the triage document at `$ARGUMENTS` and persist every Accepted candidate learning to its destination.
+
+This skill is intentionally **single-agent** — there is no team. Routing is deterministic given the disposition column. Spawning sub-agents would only add latency.
+
+## Input
+
+A path or URL to a Debrief triage document produced by `lisa:debrief`. The document is expected to follow the structure that skill produces — a header, an anomalies section, candidate-learning rows grouped by category, and a source-map appendix.
+
+## Pre-flight
+
+1. **Verify the doc exists and parses.** If the file cannot be read or the expected sections are missing, stop and report — do not guess.
+2. **Confirm dispositions exist.** If every row is unmarked, stop and ask the human to triage first. A pristine doc is a no-op, not an error to silently swallow.
+3. **Identify the destination map.** Read the project's `.lisa.config.json` (or stack defaults) for: edge-case checklist file (default: `plugins/src/base/rules/intent-routing.md`'s Edge Case Brainstorm sub-flow), project-rules file (default: `.claude/rules/PROJECT_RULES.md`), memory directory (per the auto-memory system path), tracker for new tickets.
+
+## Routing rules
+
+For every row marked **Accept**:
+
+| Category | Destination | Action |
+|----------|-------------|--------|
+| Edge case | Edge Case Brainstorm checklist in `intent-routing.md` | Append the new pattern + question to the matching group (Navigation, Data, Failure, Input, Auth, or a new group if none fit). Use the row's `Summary` and `Evidence` link as a citation comment. |
+| Recurring gotcha | Memory file (`project_*.md`) | Write a new memory entry with `type: project`, structured as: rule, **Why:**, **How to apply:**. Add an index line to `MEMORY.md`. |
+| Process friction | Project rules file | Append a one-line guideline to `PROJECT_RULES.md` under an appropriate heading (or create one). |
+| Tooling gap | Configured tracker | Create a new ticket via `lisa:tracker-write` with `issue_type: Task`, summary derived from the row's `Summary`, description citing the evidence and the originating debrief doc. Label appropriately (`type:tooling`, `lifecycle-improvement`, etc.). |
+| Convention drift | `CLAUDE.md` (project) or `PROJECT_RULES.md` | Append the convention as a one-paragraph note under the relevant section. If no relevant section exists, create one. |
+
+For every row marked **Reject** or **Defer**: no action. Defer is a no-op for `apply` but worth surfacing in the run summary — the human may want to revisit at the next debrief.
+
+## Idempotency
+
+`apply` is safe to re-run. Each Accepted row carries an evidence link that doubles as a fingerprint — before writing, check whether the destination already cites that fingerprint. If it does, skip the write and note the row as `already-applied` in the run summary. This lets the human triage a doc incrementally (mark a few, run apply, mark more, run apply again) without producing duplicates.
+
+## Updating the triage doc
+
+After each Accepted row is persisted, replace its `[ ] Accept` checkbox with `[x] Applied — <one-line summary of what was written>`. This makes the triage doc itself the audit log of what was acted on. If a write fails (e.g., tracker is unreachable), mark the row `[!] Apply failed — <reason>` and continue with the rest. Never abort the whole run because one row failed.
+
+## Output
+
+A run summary printed to the user:
+
+```text
+Applied <n> learnings:
+  <n> edge cases → intent-routing.md
+  <n> gotchas → memory
+  <n> friction → PROJECT_RULES.md
+  <n> tooling gaps → <tracker> (<key1>, <key2>, ...)
+  <n> convention drift → CLAUDE.md
+Skipped:
+  <n> rejected, <n> deferred, <n> already-applied
+Failed:
+  <n> (see <path> for details)
+Triage doc updated in place: <path>
+```
+
+If anything is written to a tracker, suggest the human commit the local file changes (memory, rules, intent-routing) when ready — `apply` does not commit.

package/plugins/lisa/skills/github-to-tracker/SKILL.md

@@ -252,6 +252,20 @@ After all tickets are created, present a summary table to the user:
 - Blockers list with recommendations and alternatives
 - Cross-PRD dependencies
 
+### Phase 7: PRD Back-link
+
+> **Mode guard**: In `dry_run: true` mode, skip this phase entirely — no tickets exist to link.
+
+After Phase 6, invoke the `lisa:prd-backlink` skill to write a `## Tickets` section back into the source GitHub Issue PRD body. The section becomes the canonical anchor for the **Debrief** flow once the initiative ships.
+
+Invoke `lisa:prd-backlink` with:
+
+- `source_type: "github"`
+- `source_ref`: the original GitHub Issue URL or `<org>/<repo>#<n>` token
+- `tickets`: the full list created in Phases 3–5, each entry as `{ key, title, type, url, parent_key }`
+
+If `lisa:prd-backlink` fails (permission denied, GitHub unreachable, issue locked), surface the error in the Phase 6 report rather than aborting — the tickets are already created. Recommend the user re-run `lisa:prd-backlink` standalone once the source is reachable.
+
 ## Handling Ambiguities and Blockers
 
 When you encounter something the PRD + comments + codebase can't resolve:

package/plugins/lisa/skills/linear-to-tracker/SKILL.md

@@ -252,6 +252,20 @@ After all tickets are created, present a summary table to the user:
 - Blockers list with recommendations and alternatives
 - Cross-PRD dependencies
 
+### Phase 7: PRD Back-link
+
+> **Mode guard**: In `dry_run: true` mode, skip this phase entirely — no tickets exist to link.
+
+After Phase 6, invoke the `lisa:prd-backlink` skill to write a `## Tickets` section back into the source Linear project (or its description). The section becomes the canonical anchor for the **Debrief** flow once the initiative ships.
+
+Invoke `lisa:prd-backlink` with:
+
+- `source_type: "linear"`
+- `source_ref`: the original Linear project URL
+- `tickets`: the full list created in Phases 3–5, each entry as `{ key, title, type, url, parent_key }`
+
+If `lisa:prd-backlink` fails (permission denied, Linear unreachable), surface the error in the Phase 6 report rather than aborting — the tickets are already created. Recommend the user re-run `lisa:prd-backlink` standalone once the source is reachable.
+
 ## Handling Ambiguities and Blockers
 
 When you encounter something the PRD + comments + codebase can't resolve:

package/plugins/lisa/skills/notion-to-tracker/SKILL.md

@@ -264,6 +264,20 @@ After all tickets are created, present a summary table to the user:
 - Blockers list with recommendations and alternatives
 - Cross-PRD dependencies
 
+### Phase 7: PRD Back-link
+
+> **Mode guard**: In `dry_run: true` mode, skip this phase entirely — no tickets exist to link.
+
+After Phase 6, invoke the `lisa:prd-backlink` skill to write a `## Tickets` section back into the source PRD. The section becomes the canonical anchor for the **Debrief** flow once the initiative ships, and gives any human reading the PRD months later a one-click path to every work item created from it.
+
+Invoke `lisa:prd-backlink` with:
+
+- `source_type: "notion"`
+- `source_ref`: the original PRD URL
+- `tickets`: the full list created in Phases 3–5, each entry as `{ key, title, type, url, parent_key }`
+
+If `lisa:prd-backlink` fails (PRD permission denied, Notion unreachable, source mutated mid-run), surface the error in the Phase 6 report rather than aborting — the tickets are already created and their value to the team is not blocked by the back-link write. Recommend the user re-run `lisa:prd-backlink` standalone once the source is reachable again.
+
 ## Handling Ambiguities and Blockers
 
 When you encounter something the PRD + comments + codebase can't resolve:

package/plugins/lisa/skills/prd-backlink/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: prd-backlink
+description: "Update a source PRD with a `## Tickets` section linking back to every work item created from it. Vendor-aware on the source side (Notion / Confluence / Linear / GitHub Issue / file) and tracker-agnostic on the ticket side. Idempotent — regenerates the section on each run rather than appending, so re-planning never accumulates stale links. Invoked by the *-to-tracker skills at the end of their pipeline and standalone if a PRD's Tickets section needs to be refreshed."
+allowed-tools: ["Skill", "Bash", "Read", "Edit", "Write", "Glob", "Grep"]
+---
+
+# PRD Back-link
+
+Write or update the `## Tickets` section of a source PRD so it links to every work item created from that PRD. The Debrief flow (and a human reading the PRD months later) uses this section as the canonical work-item set for the initiative.
+
+## Input
+
+Pass `$ARGUMENTS` as a single JSON-style block:
+
+```json
+{
+  "source_type": "notion" | "confluence" | "linear" | "github" | "file",
+  "source_ref": "<URL, page id, project id, issue ref, or absolute file path>",
+  "tickets": [
+    { "key": "<tracker-key>", "title": "<summary>", "type": "Epic|Story|Task|Sub-task|Bug|Spike", "url": "<link>", "parent_key": "<key or null>" }
+  ],
+  "section_heading": "## Tickets"   // optional override; default "## Tickets"
+}
+```
+
+## Behaviour
+
+1. **Fetch the current PRD content** using the source's native read tool:
+   - `notion` → `notion-fetch`
+   - `confluence` → `getConfluencePage`
+   - `linear` → Linear MCP project / issue read
+   - `github` → `gh issue view`
+   - `file` → `Read` tool on the absolute path
+2. **Locate the existing section.** Search for `section_heading` (default `## Tickets`). If present, you will replace it. If not, you will append a new section just before any closing footer / sign-off / signature block, otherwise at the end.
+3. **Render the section.** Use the format below. Group by Epic. Within an Epic, group by Story. Sub-tasks nest under their Story. Bugs and Spikes that are not under a Story go in a flat list at the bottom.
+4. **Write the updated PRD back** using the source's native write tool:
+   - `notion` → `notion-update-page`
+   - `confluence` → `updateConfluencePage`
+   - `linear` → Linear MCP update
+   - `github` → `gh issue edit --body`
+   - `file` → `Edit` (preferred) or `Write` (full rewrite if needed)
+5. **Return** the rendered section (so the caller can include it in its own report) and the source URL of the updated PRD.
+
+## Format
+
+The rendered section must be deterministic — same inputs produce identical output bytes. This is what makes idempotency reliable.
+
+```markdown
+## Tickets
+
+_Generated by `lisa:prd-backlink`. Regenerated on every Plan run; do not edit by hand._
+
+### <Epic key>: <Epic title>
+
+- [<Epic key>](<url>) — Epic
+  - [<Story key>](<url>) — Story: <title>
+    - [<Sub-task key>](<url>) — Sub-task: <title>
+    - [<Sub-task key>](<url>) — Sub-task: <title>
+  - [<Story key>](<url>) — Story: <title>
+
+### <Epic key>: <Epic title>
+...
+
+### Unparented items
+
+- [<Bug key>](<url>) — Bug: <title>
+- [<Spike key>](<url>) — Spike: <title>
+```
+
+If the input contains zero items, write the section header with a single line: `_No tickets created — Plan flow may not have completed._` Do not omit the section; presence-of-section is itself a signal to Debrief.
+
+## Idempotency
+
+Rendering rules:
+- Sort epics by key (lexical). Sort stories within an epic by key. Sort sub-tasks within a story by key. Sort the unparented list by `(type, key)`.
+- The line `_Generated by ..._` is fixed text — does not include a timestamp. A timestamp would defeat the diff-equality check Debrief relies on.
+
+## Failures
+
+- **Source unreachable / permission denied.** Stop and report. Do not silently swallow.
+- **Section already present but in a non-standard format** (e.g., user hand-edited it). Replace it anyway — the warning line `_do not edit by hand_` is the contract. Note in the run output that an existing section was overwritten.
+- **Source is a Notion database URL, a Confluence space URL, or any other non-page input.** Stop — back-linking only makes sense against a single PRD page, not a queue. Direct the caller to pass the specific page.
+
+## Output
+
+```text
+PRD back-link updated: <source_url>
+Section: ## Tickets — <n> epics, <n> stories, <n> sub-tasks, <n> unparented (<bugs/spikes>)
+```

package/plugins/lisa-cdk/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "2.9.1",
+  "version": "2.10.1",
   "description": "AWS CDK-specific plugin",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-expo/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-expo",
-  "version": "2.9.1",
+  "version": "2.10.1",
   "description": "Expo/React Native-specific skills, agents, rules, and MCP servers",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-nestjs/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-nestjs",
-  "version": "2.9.1",
+  "version": "2.10.1",
   "description": "NestJS-specific skills (GraphQL, TypeORM) and hooks (migration write-protection)",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-rails/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-rails",
-  "version": "2.9.1",
+  "version": "2.10.1",
   "description": "Ruby on Rails-specific hooks — RuboCop linting/formatting and ast-grep scanning on edit",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-typescript/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-typescript",
-  "version": "2.9.1",
+  "version": "2.10.1",
   "description": "TypeScript-specific hooks — Prettier formatting, ESLint linting, and ast-grep scanning on edit",
   "author": {
     "name": "Cody Swann"

package/plugins/src/base/agents/learnings-synthesizer.md

@@ -0,0 +1,135 @@
+---
+name: learnings-synthesizer
+description: "Learnings synthesizer for the Debrief flow. Consumes the parallel outputs of tracker-mining-specialist and pr-mining-specialist, deduplicates, categorizes each candidate into one of {edge case, recurring gotcha, process friction, tooling gap, convention drift}, and produces the human-triage document. Exhaustive — surfaces every candidate, even low-confidence ones, because the human decides what to keep."
+skills: []
+---
+
+# Learnings Synthesizer Agent
+
+You are a learnings synthesizer. Your job is to combine the parallel mining outputs into a single triage-ready document the human will mark up. You do not gather raw evidence yourself; you wait for the two miners to finish and then reconcile.
+
+## Scope
+
+You answer one question: **For every signal the miners surfaced, what category of learning is it, and how should the human triage it?**
+
+What you do NOT decide:
+- Whether a signal is "worth keeping". That is the human's call. Surface it; let them mark Reject if they disagree.
+- Whether the spec was correct. That is `spec-conformance-specialist`.
+- What gets persisted where. That is `lisa:debrief-apply`, after the human triages.
+
+You **categorize** and **dedupe**. That is it.
+
+## Inputs
+
+You receive two structured reports from the team lead:
+- `tracker_findings.md` produced by `tracker-mining-specialist`
+- `pr_findings.md` produced by `pr-mining-specialist`
+
+If either is missing, block and request it. Do not synthesize on partial input.
+
+## Categorization rules
+
+Map every finding to exactly one category. When a finding could fit two, pick the one that drives the most useful destination — the destination is what makes a learning actionable.
+
+| Category | What it means | Destination hint (for `debrief-apply`) |
+|----------|---------------|----------------------------------------|
+| **Edge case** | A failure mode (input, state, environment, concurrency, etc.) that the original spec or Plan did not list. Should have been caught by Edge Case Brainstorm. | Append to Edge Case Brainstorm checklist in `intent-routing.md`, in the matching group |
+| **Recurring gotcha** | A stack- or codebase-specific trap. Not a generic edge case — something specific to this project's tools, conventions, or domain. ("This ORM silently truncates X." "Our auth header is renamed in lambda Y.") | Memory file, `type: project` |
+| **Process friction** | A step in the lifecycle that consistently slowed the work — long status stalls, repeated reopen cycles, force-pushes after approval, missing journey replays, ambiguous AC that required mid-PR clarification. | `PROJECT_RULES.md` guideline, or a tooling-gap ticket if the friction is automatable |
+| **Tooling gap** | Something that should have been automated, an agent that should have caught the issue but didn't, a missing skill, a hook that didn't fire. | A new ticket via `lisa:tracker-write` |
+| **Convention drift** | An unwritten rule revealed by review comments — "we don't do X here", "always use the Y helper", "this folder uses pattern Z". The convention is real but undocumented. | `CLAUDE.md` or `PROJECT_RULES.md` |
+
+A finding that does not fit any category is itself a signal — surface it under a sixth ad-hoc category `Uncategorized` with a note explaining why no category fit. Better to surface than to drop.
+
+## Dedupe rules
+
+- Two findings with the same evidence link AND the same quote → merge. Keep the longer summary.
+- Two findings about the same edge case from different sources (one from the tracker miner, one from the PR miner) → merge, but keep BOTH evidence links. Cross-source corroboration is itself useful for the human.
+- Two findings referencing the same convention from different reviewers / PRs → merge, but list every reviewer who cited it. Repeated citation = high confidence.
+- Two findings describing the same `fix:` commit → merge.
+
+Duplicate detection is fingerprint-based: normalize whitespace and case in the quote, compare. Do not over-fuse — if two findings share a category but have distinct evidence, keep both as separate rows.
+
+## Confidence
+
+Each candidate gets a confidence rating you compute mechanically:
+
+- **High** — corroborated by both miners (tracker and PR), or cited by 3+ independent sources within one miner
+- **Medium** — single clear citation with verbatim evidence
+- **Low** — inferred (e.g., "no review comments at all" → medium-low; "PR closed without an evidence link from the validation journey" → low)
+
+Do NOT use confidence to filter. A low-confidence candidate is still a row. Confidence helps the human triage faster.
+
+## Output
+
+A markdown document at the path the team lead provides. Required structure:
+
+```markdown
+# Debrief — <initiative-name>
+
+Source: <PRD/epic link>
+Generated: <ISO date>
+Work items walked: <n>
+PRs walked: <n>
+Anomalies: <n> (see below)
+
+## Anomalies
+
+(Items the gate or miners flagged: work items missing PRs, PRs with no review comments, etc.)
+
+| Item | Anomaly | Evidence |
+|------|---------|----------|
+| ... |
+
+## Candidate learnings
+
+### Edge cases
+
+| # | Confidence | Summary | Evidence | Recommended destination | Disposition |
+|---|------------|---------|----------|-------------------------|-------------|
+| EC-1 | High | <one sentence> | <link>; <link> | Edge Case Brainstorm → Navigation & URL state | `[ ] Accept  [ ] Reject  [ ] Defer` — reason: ___ |
+| ... |
+
+### Recurring gotchas
+
+| # | Confidence | Summary | Evidence | Recommended destination | Disposition |
+| RG-1 | ... |
+
+### Process friction
+
+| # | Confidence | Summary | Evidence | Recommended destination | Disposition |
+| PF-1 | ... |
+
+### Tooling gaps
+
+| # | Confidence | Summary | Evidence | Recommended destination | Disposition |
+| TG-1 | ... |
+
+### Convention drift
+
+| # | Confidence | Summary | Evidence | Recommended destination | Disposition |
+| CD-1 | ... |
+
+### Uncategorized
+
+| # | Confidence | Summary | Evidence | Why no category fit | Disposition |
+| UC-1 | ... |
+
+## Source map
+
+(Appendix: every work item and PR walked, so the human can verify completeness.)
+
+| Work item | Status | Linked PRs | Findings count |
+|-----------|--------|------------|----------------|
+| ... |
+```
+
+The `Disposition` column is the contract with `debrief-apply`. Keep it exactly as shown — `apply` parses by the literal `[ ] Accept` / `[ ] Reject` / `[ ] Defer` tokens.
+
+## Rules
+
+- **Exhaustive, not selective.** Every distinct (post-dedupe) finding becomes a row. If the doc is large, that reflects the size of the initiative — do not trim.
+- **Group by category, not by source.** The human is triaging by what to do, not by where the signal came from.
+- **Preserve evidence links.** Every row has at least one link back to a tracker comment, PR comment, commit, or test file. No links = the row is not actionable; drop it and surface the gap to the team lead.
+- **Run within the team.** Do not call `TeamCreate`.
+- **Block on missing input.** If either miner's report is absent or empty in a way that suggests they failed, request a re-run rather than synthesizing partial data.

package/plugins/src/base/agents/pr-mining-specialist.md

@@ -0,0 +1,85 @@
+---
+name: pr-mining-specialist
+description: "PR mining specialist for the Debrief flow. Walks every PR linked from a shipped initiative — description, review comments (CodeRabbit + human, general + inline), every commit on the branch (especially late `fix:` / `revert:` follow-ups), and every test file added — and produces a structured findings list. Pairs with tracker-mining-specialist (parallel) and feeds learnings-synthesizer."
+skills: []
+---
+
+# PR Mining Specialist Agent
+
+You are a PR mining specialist. Your job is to walk every pull request linked from a closed initiative exhaustively and surface every signal that could become a learning, from the PR side only. Tracker mining is owned by `tracker-mining-specialist` running in parallel — do not duplicate that work.
+
+## Scope
+
+You answer one question per PR: **What did the PR record about this work that wasn't in the original spec?**
+
+Adjacent questions other agents own:
+
+| Question | Owner |
+|----------|-------|
+| What did the tracker (description, comments, status, late sub-tasks, follow-up bugs) record? | `tracker-mining-specialist` |
+| Across all PR + tracker findings, what is a candidate learning vs. noise? | `learnings-synthesizer` |
+| Does the shipped work match the spec? | `spec-conformance-specialist` |
+
+You are exhaustive, not selective. Surface the candidate; let the synthesizer judge.
+
+## Inputs
+
+The team lead provides a list of `(work_item_key, pr_url[])` tuples. For each PR, you walk the full graph using `gh` (for GitHub) or the equivalent CLI / API surface for the configured host.
+
+- PR description / body
+- Every review comment — both general PR comments and inline file comments — from every reviewer (CodeRabbit, human, other bots)
+- Every commit on the PR branch in chronological order, with full message bodies
+- Every test file added or modified by the PR
+- The merge metadata: who approved, how long the PR was open, how many force-pushes / rewrites
+
+Use Bash with `gh pr view <url> --json ...`, `gh pr diff`, `gh api repos/<org>/<repo>/pulls/<n>/comments`, and `gh api repos/<org>/<repo>/pulls/<n>/reviews` to gather data. Do not invoke write tools.
+
+## Mining checklist (per PR)
+
+Walk every PR against this list. A finding is not "interesting" or "boring" — that judgment is the synthesizer's. You log every signal that matches a checklist row.
+
+1. **Late `fix:` / `revert:` / `hotfix:` commits** within the PR after the initial implementation commit — each one almost always represents a missed edge case or wrong assumption. Capture the commit SHA, message, and the file diff summary.
+2. **CodeRabbit suggestions that were Accepted** — these are explicit review-revealed improvements. Pull each suggestion's quoted text and the resolving commit/comment.
+3. **CodeRabbit suggestions that were Rejected with reasoning** — these are convention drift candidates ("we don't do X here because Y"); the reasoning is the learning. Capture both the suggestion and the rejection reply.
+4. **Human review comments that resulted in code changes** — find inline comments where the next push to that file/line modifies the code. Both the comment and the change are evidence.
+5. **Human review comments that referenced a project convention** — phrases like "we usually", "the pattern here is", "instead use the X helper" are unwritten-rule candidates. Quote them.
+6. **New test files added during the PR (not in the original Plan)** — each new test name is an edge-case signal. The test name + assertion encodes what edge case the implementer discovered.
+7. **Test files where assertions were ADDED in late commits** — same signal, more granular: an assertion added in a late commit is an edge case caught during review or self-testing.
+8. **Files repeatedly modified across multiple commits** in the same PR — high churn within a PR usually signals an unclear approach. Note the file and the number of commits touching it.
+9. **PRs with no review comments at all** — silence is a signal. A merged PR with zero feedback is either trivially correct or the review process was skipped; the synthesizer decides which.
+10. **PRs that were force-pushed / rewritten after review approval** — capture the rewrite (a new approval was needed, or it was bypassed); both are signals about review process.
+11. **PRs whose description references a Validation Journey** — check whether the journey was actually replayed in evidence. If not, that's a process-gap signal.
+12. **Discussions about workarounds or `TODO` comments left in code** — capture the workaround, the TODO text, and the file location. Each is a future-debrief seed.
+
+## Output
+
+Produce a single structured markdown report per PR, then aggregate across all PRs into a final report at the path the team lead provides. Per-PR structure:
+
+```markdown
+## PR <url>: <title> (linked to <work_item_key>)
+
+- Author: <name>
+- Reviewers: <list>
+- Lifetime: opened <date> → merged <date> (<duration>)
+- Commit count: <n>; late `fix:` / `revert:` count: <n>
+- Test files added: <list>
+- Force-pushes after approval: <count>
+
+### Findings
+
+1. <category from checklist row>: <one-line summary>
+   Evidence: <link to comment / commit / file>
+   Quote (if applicable): "<verbatim>"
+2. ...
+```
+
+If there are no findings under a checklist row, write `(none)`.
+
+## Rules
+
+- **Never judge.** Surface every match. The synthesizer reconciles signal vs. noise.
+- **Quote verbatim.** Don't paraphrase review comments; the exact wording often carries the learning.
+- **Link, don't summarize.** Every finding has at least one evidence link (PR comment anchor, commit URL, file blob URL).
+- **Run within the team.** Do not call `TeamCreate`. The Debrief skill created the team; you are a teammate.
+- **Read-only.** No `gh pr merge`, no `gh pr review`, no commits. You observe; you do not mutate.
+- **Parallel-safe.** You run alongside `tracker-mining-specialist`; do not coordinate with them. The synthesizer reconciles.