@gobing-ai/spur 0.3.47 → 0.3.49
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.claude-plugin/marketplace.json +1 -1
- package/config/config.example.yaml +94 -15
- package/config/transition-shims.json +33 -0
- package/config/workflows/basic.yaml +2 -0
- package/config/workflows/docs-pipeline.yaml +2 -0
- package/config/workflows/feature-dev.yaml +8 -0
- package/config/workflows/idea-pipeline.yaml +10 -0
- package/config/workflows/planning-pipeline.yaml +4 -0
- package/config/workflows/pr-review.yaml +338 -0
- package/config/workflows/task-pipeline.yaml +8 -0
- package/config/workflows/wayfinder-resolution.yaml +4 -0
- package/config/workflows/wrapup-pipeline.yaml +18 -1
- package/package.json +8 -8
- package/plugins/sp/README.md +9 -6
- package/plugins/sp/agents/expert-spur.md +1 -0
- package/plugins/sp/commands/dev-arch.md +2 -1
- package/plugins/sp/commands/dev-brainstorm.md +2 -1
- package/plugins/sp/commands/dev-changelog.md +1 -0
- package/plugins/sp/commands/dev-daily.md +1 -0
- package/plugins/sp/commands/dev-debug.md +2 -1
- package/plugins/sp/commands/dev-dogfood.md +2 -1
- package/plugins/sp/commands/{dev-featurechange.md → dev-feature-change.md} +8 -10
- package/plugins/sp/commands/dev-find-conflict.md +2 -1
- package/plugins/sp/commands/dev-find-issue.md +36 -43
- package/plugins/sp/commands/dev-find-next.md +5 -4
- package/plugins/sp/commands/dev-fixall.md +1 -0
- package/plugins/sp/commands/dev-gitmsg.md +1 -0
- package/plugins/sp/commands/dev-gtd.md +12 -12
- package/plugins/sp/commands/dev-handover.md +1 -0
- package/plugins/sp/commands/dev-history-load.md +63 -0
- package/plugins/sp/commands/dev-idea.md +1 -0
- package/plugins/sp/commands/dev-next.md +2 -1
- package/plugins/sp/commands/dev-parallel.md +2 -1
- package/plugins/sp/commands/dev-plan.md +2 -1
- package/plugins/sp/commands/dev-pr-review.md +39 -0
- package/plugins/sp/commands/dev-refine.md +5 -3
- package/plugins/sp/commands/dev-refineall.md +2 -1
- package/plugins/sp/commands/dev-refresh.md +2 -1
- package/plugins/sp/commands/dev-reverse.md +2 -1
- package/plugins/sp/commands/dev-review.md +2 -1
- package/plugins/sp/commands/dev-run.md +3 -2
- package/plugins/sp/commands/dev-runall.md +3 -2
- package/plugins/sp/commands/dev-simplify.md +2 -1
- package/plugins/sp/commands/dev-unit.md +2 -1
- package/plugins/sp/commands/dev-verify.md +2 -1
- package/plugins/sp/commands/dev-verifyall.md +2 -1
- package/plugins/sp/commands/dev-wrap.md +7 -5
- package/plugins/sp/commands/dev-wrapall.md +7 -5
- package/plugins/sp/commands/rule-add.md +1 -0
- package/plugins/sp/commands/rule-refine.md +1 -0
- package/plugins/sp/commands/rule-scan.md +1 -0
- package/plugins/sp/commands/spur-init.md +1 -0
- package/plugins/sp/commands/workflow-add.md +1 -0
- package/plugins/sp/commands/workflow-refine.md +1 -0
- package/plugins/sp/hooks/careful-guard.ts +5 -80
- package/plugins/sp/hooks/destructive-policy.ts +146 -0
- package/plugins/sp/hooks/pi/guard-extension.ts +33 -46
- package/plugins/sp/hooks/task-file-policy.ts +31 -0
- package/plugins/sp/hooks/task-write-guard.ts +4 -0
- package/plugins/sp/plugin.json +1 -1
- package/plugins/sp/references/roles.md +106 -0
- package/plugins/sp/scripts/feature-sync-bounded.ts +28 -2
- package/plugins/sp/scripts/history-load.ts +400 -0
- package/plugins/sp/scripts/pr-reviewing.ts +867 -0
- package/plugins/sp/scripts/stage-registry-adapter.ts +66 -31
- package/plugins/sp/scripts/surface-drift-inventory.ts +908 -0
- package/plugins/sp/scripts/task-size-precheck.ts +30 -4
- package/plugins/sp/scripts/transition-shim-check.ts +238 -0
- package/plugins/sp/scripts/validate-commands.ts +33 -2
- package/plugins/sp/scripts/validate-flag-contracts.ts +5 -2
- package/plugins/sp/skills/code-implementation/SKILL.md +9 -1
- package/plugins/sp/skills/code-verification/SKILL.md +29 -28
- package/plugins/sp/skills/issue-finding/SKILL.md +123 -141
- package/plugins/sp/skills/issue-finding/examples/expected-findings.json +1 -1
- package/plugins/sp/skills/issue-finding/references/session-formats.md +87 -90
- package/plugins/sp/skills/next-feature/SKILL.md +6 -6
- package/plugins/sp/skills/next-feature/references/handoff-routing.md +5 -5
- package/plugins/sp/skills/next-feature/references/signal-derivation.md +7 -2
- package/plugins/sp/skills/next-router/SKILL.md +1 -1
- package/plugins/sp/skills/parallel-execution/references/dispatch-surface.md +40 -2
- package/plugins/sp/skills/pr-reviewing/SKILL.md +285 -0
- package/plugins/sp/skills/spur-cli/SKILL.md +3 -0
- package/plugins/sp/skills/spur-cli/references/agent.md +12 -7
- package/plugins/sp/skills/spur-cli/references/features/hierarchy-mece.md +5 -5
- package/plugins/sp/skills/spur-cli/references/features.md +1 -1
- package/plugins/sp/skills/spur-cli/references/team.md +10 -3
- package/plugins/sp/skills/spur-dev/SKILL.md +2 -0
- package/plugins/sp/skills/spur-dev/references/ac-style-guide.md +17 -0
- package/plugins/sp/skills/spur-dev/references/cross-cutting.md +44 -23
- package/plugins/sp/skills/spur-dev/references/dev-operations.md +14 -11
- package/plugins/sp/skills/spur-dev/references/execution-workflow.md +14 -12
- package/plugins/sp/skills/spur-dev/references/flag-glossary.md +28 -7
- package/plugins/sp/skills/spur-dev/references/gate-checklists.md +2 -0
- package/plugins/sp/skills/spur-dev/references/inline-pipeline-driver.md +12 -2
- package/schemas/spur-config.schema.json +47 -3
- package/spur.js +12223 -7716
- package/web/_astro/BoardApp.8hiqShQn.js +1 -0
- package/web/_astro/{BoardApp.DKyrGxdo.js → BoardApp.BjQUNhuj.js} +74 -74
- package/web/_astro/{TaskDetail.6-27_LMa.js → TaskDetail.CVBuD6dF.js} +1 -1
- package/web/_astro/{arc.Df-9AQvS.js → arc.BMMjdODi.js} +1 -1
- package/web/_astro/{architectureDiagram-3BPJPVTR.VAI_-paS.js → architectureDiagram-3BPJPVTR.BU5ShzXf.js} +1 -1
- package/web/_astro/{blockDiagram-GPEHLZMM.DFpUY1ue.js → blockDiagram-GPEHLZMM.Bj1iEqPD.js} +1 -1
- package/web/_astro/{c4Diagram-AAUBKEIU.CF8doOpg.js → c4Diagram-AAUBKEIU.vX8wepCL.js} +1 -1
- package/web/_astro/channel.EwdSemIC.js +1 -0
- package/web/_astro/{chunk-2J33WTMH.BnjK3fjt.js → chunk-2J33WTMH.BKAipTym.js} +1 -1
- package/web/_astro/{chunk-4BX2VUAB.x6ZDnJKq.js → chunk-4BX2VUAB.B68XkPG7.js} +1 -1
- package/web/_astro/{chunk-55IACEB6.zY-0uu7w.js → chunk-55IACEB6.BmeDLcrc.js} +1 -1
- package/web/_astro/{chunk-727SXJPM.BZxKg_Vi.js → chunk-727SXJPM.PDuBA3Kw.js} +1 -1
- package/web/_astro/{chunk-AQP2D5EJ.Cpi9G9Td.js → chunk-AQP2D5EJ.C7A044za.js} +1 -1
- package/web/_astro/{chunk-FMBD7UC4.DWTB-Pif.js → chunk-FMBD7UC4.BtzKKFqR.js} +1 -1
- package/web/_astro/{chunk-ND2GUHAM.BPDQbiOG.js → chunk-ND2GUHAM.BJuDeeOy.js} +1 -1
- package/web/_astro/{chunk-QZHKN3VN.BRWIcuoM.js → chunk-QZHKN3VN.DSeMDgcQ.js} +1 -1
- package/web/_astro/{classDiagram-4FO5ZUOK.mGTCZsDO.js → classDiagram-4FO5ZUOK.D53Q4tCw.js} +1 -1
- package/web/_astro/{classDiagram-v2-Q7XG4LA2.mGTCZsDO.js → classDiagram-v2-Q7XG4LA2.D53Q4tCw.js} +1 -1
- package/web/_astro/{cose-bilkent-S5V4N54A.D1GEut-z.js → cose-bilkent-S5V4N54A.c712AFRH.js} +1 -1
- package/web/_astro/{dagre-BM42HDAG.BV0XG9Do.js → dagre-BM42HDAG.D-idisph.js} +1 -1
- package/web/_astro/{diagram-2AECGRRQ.DzpYxsjo.js → diagram-2AECGRRQ.DLgnsJCU.js} +1 -1
- package/web/_astro/{diagram-5GNKFQAL.Cm9YzJh4.js → diagram-5GNKFQAL.BiaxBVqx.js} +1 -1
- package/web/_astro/{diagram-KO2AKTUF.BjhottUj.js → diagram-KO2AKTUF.C8HX1vd8.js} +1 -1
- package/web/_astro/{diagram-LMA3HP47.BFsQW5kb.js → diagram-LMA3HP47.CfqDLLes.js} +1 -1
- package/web/_astro/{diagram-OG6HWLK6.8pdpzSWO.js → diagram-OG6HWLK6.15SDiEed.js} +1 -1
- package/web/_astro/{erDiagram-TEJ5UH35.Bd7KUJmJ.js → erDiagram-TEJ5UH35.DksYtOYM.js} +1 -1
- package/web/_astro/{flowDiagram-I6XJVG4X.7LWffkaE.js → flowDiagram-I6XJVG4X.DR_Au-HV.js} +1 -1
- package/web/_astro/{ganttDiagram-6RSMTGT7.BeDcO5tI.js → ganttDiagram-6RSMTGT7.CHhHrffI.js} +1 -1
- package/web/_astro/{gitGraphDiagram-PVQCEYII.Ca4n730A.js → gitGraphDiagram-PVQCEYII.B2Xehvam.js} +1 -1
- package/web/_astro/{index.Dbvuw6d4.css → index.DAxu50UF.css} +1 -1
- package/web/_astro/{infoDiagram-5YYISTIA.B0OakQYb.js → infoDiagram-5YYISTIA.C9c3CNNN.js} +1 -1
- package/web/_astro/{ishikawaDiagram-YF4QCWOH.DSmNQe-1.js → ishikawaDiagram-YF4QCWOH.BibUHkh8.js} +1 -1
- package/web/_astro/{journeyDiagram-JHISSGLW.Cy5ruEUu.js → journeyDiagram-JHISSGLW.BYoVHiyO.js} +1 -1
- package/web/_astro/{kanban-definition-UN3LZRKU.CUJXub0p.js → kanban-definition-UN3LZRKU.CM1K5wHE.js} +1 -1
- package/web/_astro/{linear.DC1jCCXn.js → linear.SPpjJUb-.js} +1 -1
- package/web/_astro/{mermaid.core.DxVP99Ab.js → mermaid.core.BAgx3nnb.js} +4 -4
- package/web/_astro/{mindmap-definition-RKZ34NQL.D0MaV6sJ.js → mindmap-definition-RKZ34NQL.D35oPG1R.js} +1 -1
- package/web/_astro/{pieDiagram-4H26LBE5.DCC6_q32.js → pieDiagram-4H26LBE5.DiWuRwk7.js} +1 -1
- package/web/_astro/{quadrantDiagram-W4KKPZXB.BeUOAM7C.js → quadrantDiagram-W4KKPZXB.B9PBzTWn.js} +1 -1
- package/web/_astro/{requirementDiagram-4Y6WPE33.Dbl4MASO.js → requirementDiagram-4Y6WPE33.CYuuamFN.js} +1 -1
- package/web/_astro/{sankeyDiagram-5OEKKPKP.HsLg0VS4.js → sankeyDiagram-5OEKKPKP.W24UhhtD.js} +1 -1
- package/web/_astro/{sequenceDiagram-3UESZ5HK.DT7DJTnZ.js → sequenceDiagram-3UESZ5HK.BpbNjA51.js} +1 -1
- package/web/_astro/{stateDiagram-AJRCARHV.d_ju1Vr1.js → stateDiagram-AJRCARHV.DqVsHudf.js} +1 -1
- package/web/_astro/{stateDiagram-v2-BHNVJYJU.DMCAjMJ4.js → stateDiagram-v2-BHNVJYJU.CzwHYX81.js} +1 -1
- package/web/_astro/{timeline-definition-PNZ67QCA.DNOHr62_.js → timeline-definition-PNZ67QCA.Bc3B6djw.js} +1 -1
- package/web/_astro/{vennDiagram-CIIHVFJN.B7dUy-1W.js → vennDiagram-CIIHVFJN.C-D5rh8O.js} +1 -1
- package/web/_astro/{wardley-L42UT6IY.DEqOXvBh.js → wardley-L42UT6IY.D7PdYCqn.js} +1 -1
- package/web/_astro/{wardleyDiagram-YWT4CUSO.BCRb2p6x.js → wardleyDiagram-YWT4CUSO.CwmJKXF3.js} +1 -1
- package/web/_astro/{xychartDiagram-2RQKCTM6.NxVQLdBh.js → xychartDiagram-2RQKCTM6.avDYnLsb.js} +1 -1
- package/web/index.html +2 -2
- package/web/_astro/BoardApp.Ce6zJYAH.js +0 -1
- package/web/_astro/channel.Uhm9O3UV.js +0 -1
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: issue-finding
|
|
3
|
-
description: "
|
|
3
|
+
description: "Render the session forensics report, analyze agent session logs, find performance bottlenecks, propose fixes, and optionally create a structured task. Triggers: find issues, post-mortem, session review, topic focus."
|
|
4
4
|
license: Apache-2.0
|
|
5
|
-
version:
|
|
5
|
+
version: 2.0.0
|
|
6
6
|
metadata:
|
|
7
7
|
author: spur
|
|
8
8
|
platforms: "claude-code,codex,openclaw,opencode,antigravity,pi"
|
|
@@ -11,8 +11,7 @@ metadata:
|
|
|
11
11
|
- pipeline
|
|
12
12
|
- inversion
|
|
13
13
|
pipeline_steps:
|
|
14
|
-
-
|
|
15
|
-
- analyze
|
|
14
|
+
- report
|
|
16
15
|
- identify
|
|
17
16
|
- propose
|
|
18
17
|
- generate
|
|
@@ -30,11 +29,13 @@ see_also:
|
|
|
30
29
|
|
|
31
30
|
# sp:issue-finding — Session Log Issue Finder
|
|
32
31
|
|
|
33
|
-
|
|
34
|
-
fixes, and
|
|
32
|
+
Render the forensic report for agent session logs, identify performance bottlenecks and behavioral
|
|
33
|
+
anti-patterns, propose fixes, and — only with `--create-task` — create a structured task file.
|
|
35
34
|
|
|
36
|
-
|
|
37
|
-
(
|
|
35
|
+
**Default output is a report, not a task** (task 0556): the typed data plane
|
|
36
|
+
(`spur history report --mode forensics`) renders the quantitative sections; this skill authors the
|
|
37
|
+
interpretation on top. It codifies the forensic analysis performed after the J4 batch execution
|
|
38
|
+
(task 0379), reusable for any set of agent sessions.
|
|
38
39
|
|
|
39
40
|
**Honesty contract:** install-time skill packaging works on all declared platforms. **Native
|
|
40
41
|
session forensics depth varies by agent** — OMP is the deepest documented adapter; other sources
|
|
@@ -61,23 +62,23 @@ bottlenecks", "post-mortem", "what went wrong", "why was this slow"
|
|
|
61
62
|
|
|
62
63
|
## Arguments
|
|
63
64
|
|
|
64
|
-
| Argument | Description
|
|
65
|
-
| --------------------------------- |
|
|
66
|
-
| `[topic]` | Optional free-text focus or smart positional input (see below). Narrows IDENTIFY/PROPOSE/GENERATE;
|
|
67
|
-
| `--sessions <glob>` | Session JSONL file(s) or directory to analyze. When omitted, uses the most recent sessions for the resolved source + current project.
|
|
65
|
+
| Argument | Description | Default |
|
|
66
|
+
| --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------- |
|
|
67
|
+
| `[topic]` | Optional free-text focus or smart positional input (see below). Narrows IDENTIFY/PROPOSE/GENERATE; the report still covers all selected sessions. | (full taxonomy) |
|
|
68
|
+
| `--sessions <glob>` | Session JSONL file(s) or directory to analyze. When omitted, uses the most recent sessions for the resolved source + current project. Pins the raw-fallback path (below). | (most recent) |
|
|
68
69
|
| `--source <name>` | Session log source: `auto`, `omp`, `claude`, `codex`, `gemini`, `opencode`, `antigravity`, `openclaw`, `pi`. `auto` = cwd agent when known, else `omp` if present, else first existing default root. | `auto` |
|
|
69
|
-
| `--feature <id>` | Feature ID to link the generated task to (e.g., `H51`).
|
|
70
|
-
| `--template <name>` | Task template: `meta` (multi-fix umbrella), `issue` (single finding), or `standard`.
|
|
71
|
-
| `--priority <P0\|P1\|P2\|P3>` | **Task** priority frontmatter (`spur task update --priority`). Not bottleneck severity.
|
|
72
|
-
| `--severity <S0\|S1\|S2>` | Minimum **bottleneck** severity to keep after ranking (S0 most severe).
|
|
73
|
-
| `--category <list>` | Comma-separated bottleneck categories to keep (see IDENTIFY table ids).
|
|
74
|
-
| `--since <iso>` / `--until <iso>` | Optional wall-clock bounds on session start times (when timestamps are available).
|
|
75
|
-
| `--top <n>` | Cap the number of requirements / fixes written into the task.
|
|
76
|
-
| `--min-cost <duration>` | Drop bottlenecks whose estimated waste is below this floor (e.g. `30m`, `2h`). Applied after severity ranking.
|
|
77
|
-
| `--strict-topic` | When `[topic]` is set, drop off-topic bottlenecks even if they dominate wall time.
|
|
78
|
-
| `--
|
|
79
|
-
| `--
|
|
80
|
-
| `--json` | JSON findings to stdout
|
|
70
|
+
| `--feature <id>` | Feature ID to link the generated task to (e.g., `H51`). | (none) |
|
|
71
|
+
| `--template <name>` | Task template: `meta` (multi-fix umbrella), `issue` (single finding), or `standard`. | `meta` |
|
|
72
|
+
| `--priority <P0\|P1\|P2\|P3>` | **Task** priority frontmatter (`spur task update --priority`). Not bottleneck severity. | `P2` |
|
|
73
|
+
| `--severity <S0\|S1\|S2>` | Minimum **bottleneck** severity to keep after ranking (S0 most severe). | (all) |
|
|
74
|
+
| `--category <list>` | Comma-separated bottleneck categories to keep (see IDENTIFY table ids). | `all` |
|
|
75
|
+
| `--since <iso>` / `--until <iso>` | Optional wall-clock bounds on session start times (when timestamps are available). | (none) |
|
|
76
|
+
| `--top <n>` | Cap the number of requirements / fixes written into the task. | (no cap) |
|
|
77
|
+
| `--min-cost <duration>` | Drop bottlenecks whose estimated waste is below this floor (e.g. `30m`, `2h`). Applied after severity ranking. | (none) |
|
|
78
|
+
| `--strict-topic` | When `[topic]` is set, drop off-topic bottlenecks even if they dominate wall time. | off |
|
|
79
|
+
| `--agent <name>` | Narrow sessions to one agent/subagent executor name. | (all agents) |
|
|
80
|
+
| `--create-task` | Opt **in** to task creation (GENERATE). Default mode stops after the report. | off |
|
|
81
|
+
| `--json` | JSON findings to stdout instead of the markdown report. Composable with `--create-task`. | off |
|
|
81
82
|
|
|
82
83
|
### Smart positional `[topic]`
|
|
83
84
|
|
|
@@ -104,54 +105,68 @@ Severity thresholds:
|
|
|
104
105
|
|
|
105
106
|
### Output mode matrix
|
|
106
107
|
|
|
107
|
-
| Flags | Create task | Stdout
|
|
108
|
-
| ---------------------- | ----------- |
|
|
109
|
-
| (default) |
|
|
110
|
-
| `--
|
|
111
|
-
| `--
|
|
112
|
-
| `--
|
|
108
|
+
| Flags | Create task | Stdout |
|
|
109
|
+
| ---------------------- | ----------- | ------------------------------- |
|
|
110
|
+
| (default) | no | markdown report |
|
|
111
|
+
| `--json` | no | JSON findings (`task: null`) |
|
|
112
|
+
| `--create-task` | yes | short summary + WBS |
|
|
113
|
+
| `--create-task --json` | yes | JSON findings with `task` block |
|
|
113
114
|
|
|
114
|
-
|
|
115
|
+
Without `--create-task` the run is report-only — never create a task unasked.
|
|
115
116
|
|
|
116
|
-
|
|
117
|
+
### Removed flags (task 0556)
|
|
118
|
+
|
|
119
|
+
| Removed flag | Old behavior | Replacement |
|
|
120
|
+
| --------------- | ------------------------------------ | ---------------------------------------------------------------------- |
|
|
121
|
+
| `--use-history` | Opt in to the `spur history` bridge | None — the typed data plane is now the default REPORT path |
|
|
122
|
+
| `--no-task` | Report to stdout, skip task creation | None — report-only is the default; pass `--create-task` to opt **in** |
|
|
123
|
+
|
|
124
|
+
If an invocation passes either removed flag, do not swallow it as generic unknown-option noise:
|
|
125
|
+
reject the invocation with a message naming the replacement above.
|
|
126
|
+
|
|
127
|
+
## The 4-Phase Protocol
|
|
117
128
|
|
|
118
129
|
```
|
|
119
|
-
sessions (
|
|
120
|
-
→
|
|
121
|
-
→ ANALYZE extract metrics: tool calls, compactions, test runs, guard failures
|
|
130
|
+
sessions (typed ETL via `spur history` — or raw JSONL under the three fallback conditions)
|
|
131
|
+
→ REPORT render the forensic report: 8 CLI-derivable sections; author analysis on top
|
|
122
132
|
→ IDENTIFY rank bottlenecks by time cost; filter by topic/category/severity
|
|
123
133
|
→ PROPOSE design fixes for in-scope root causes; estimate time savings
|
|
124
|
-
→ GENERATE create a structured task via `spur task create` (
|
|
134
|
+
→ GENERATE create a structured task via `spur task create` (only with --create-task)
|
|
125
135
|
```
|
|
126
136
|
|
|
127
|
-
### Phase 1:
|
|
137
|
+
### Phase 1: REPORT — Data plane first
|
|
128
138
|
|
|
129
|
-
**
|
|
139
|
+
**Primary path (typed sources):** `spur history report --mode forensics` (task 0555).
|
|
130
140
|
|
|
131
|
-
|
|
141
|
+
```bash
|
|
142
|
+
# 0568 R4: SPUR_BIN env > local CLI > PATH — stale PATH spur fails history import.
|
|
143
|
+
SPUR_BIN="${SPUR_BIN:-$([ -f apps/cli/src/index.ts ] && echo 'bun apps/cli/src/index.ts' || echo spur)}"
|
|
132
144
|
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
timestamped session set (include subagent session files when the layout has them).
|
|
138
|
-
4. Apply `--since` / `--until` when session start timestamps are available.
|
|
139
|
-
5. Build a session inventory table:
|
|
145
|
+
$SPUR_BIN history import --source <source> --json # checkpoint resume
|
|
146
|
+
$SPUR_BIN history analyze --json # writes versioned artifact (0554)
|
|
147
|
+
$SPUR_BIN history report --mode forensics # pure renderer; latest artifact pointer
|
|
148
|
+
```
|
|
140
149
|
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
150
|
+
The forensics renderer emits **8 CLI-derivable sections**: Session Data Summary, Tool Breakdown,
|
|
151
|
+
Token Profile (tokens + cache-hit ratio — never prices), Time Decomposition, Per-Phase, Per-Tool
|
|
152
|
+
Execution Time, Bottleneck Ranking, and the Raw Data appendix. The CLI does not write the
|
|
153
|
+
interpretation: IDENTIFY and PROPOSE below author the root-cause narrative, fix design, and
|
|
154
|
+
acceptance criteria on top of the rendered data — that analysis is why this skill exists.
|
|
145
155
|
|
|
146
|
-
|
|
147
|
-
(High = known adapter + readable tool events; Medium = path found, format partial;
|
|
148
|
-
Low = operator-supplied paths only).
|
|
156
|
+
**Raw JSONL fallback — exactly three conditions** (0492 R7):
|
|
149
157
|
|
|
150
|
-
|
|
158
|
+
1. The resolved `--source` has **no typed mapper** in the importer.
|
|
159
|
+
2. The operator passed **explicit `--sessions`** — respect the pin; do not reconcile the pinned
|
|
160
|
+
files against the database.
|
|
161
|
+
3. You need a **primitive the typed tables do not retain** (e.g. identical-command loop strings) —
|
|
162
|
+
parse raw lines for just that primitive and keep the data plane for the rest.
|
|
151
163
|
|
|
152
|
-
**
|
|
164
|
+
A source with a typed mapper must **not** trigger wholesale raw parsing. If an import fails or the
|
|
165
|
+
DB is empty, note that aggregate data is unavailable and fall back strictly per the conditions
|
|
166
|
+
above.
|
|
153
167
|
|
|
154
|
-
**
|
|
168
|
+
**Fallback parser — portable signals to count** (map field names per source — see
|
|
169
|
+
[references/session-formats.md](references/session-formats.md)):
|
|
155
170
|
|
|
156
171
|
| Signal | Metric |
|
|
157
172
|
| --------------------------------------------------------------------- | -------------------------------- |
|
|
@@ -164,34 +179,11 @@ sessions (JSONL — source-dependent roots; see session-formats.md)
|
|
|
164
179
|
| Identical command string repeated 3+ times | Loop candidate |
|
|
165
180
|
|
|
166
181
|
**Extraction approach:** read each JSONL file line-by-line; parse tool name + command inputs;
|
|
167
|
-
count identical commands for loop detection.
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
When `--use-history` is set, the **selected-file history bridge** supplies ETL aggregates for the
|
|
173
|
-
frozen session set (task 0507 R3):
|
|
174
|
-
|
|
175
|
-
1. **Freeze Phase 1's selected OMP JSONL files once** — the same inventory the raw analysis reads.
|
|
176
|
-
Discovery roots: the normal OMP session root (`~/.omp/agent/sessions/`) **and**
|
|
177
|
-
`.spur/run/<run-id>/agent-sessions/<omp-executor>/*.jsonl` for workflow subprocess sessions.
|
|
178
|
-
Never import a broad `.spur/run` scan and never run a full/source-root reconciliation here.
|
|
179
|
-
2. **Import each frozen file once, through the source-local CLI**, with single-file `force-file`
|
|
180
|
-
mode:
|
|
181
|
-
`bun run apps/cli/src/index.ts history import --source omp --file <absolute-file> --mode force-file --json`.
|
|
182
|
-
The importer derives the session key from the filename; use the same stem for analysis.
|
|
183
|
-
3. **Analyze scoped to that key**: `history analyze --session <filename-stem> --json`.
|
|
184
|
-
4. Use the artifact for the aggregates ETL can represent — tokens, cost, messages, tool calls,
|
|
185
|
-
loops, and assistant response duration. **Continue parsing the same raw files** for command text,
|
|
186
|
-
compactions, test/guard retries, tool execution duration/status/errors, and every other signal
|
|
187
|
-
the ETL does not carry.
|
|
188
|
-
|
|
189
|
-
ETL supplies normalized aggregates; it is **not** a substitute for raw tool-loop evidence. If an
|
|
190
|
-
import fails or the DB is empty, continue with raw logs and note that cost data is unavailable.
|
|
191
|
-
Before any ad-hoc verification SQL against `history_*` tables, follow the schema-first rule in
|
|
192
|
-
[references/session-formats.md](references/session-formats.md) — inspect the live schema once.
|
|
193
|
-
|
|
194
|
-
### Phase 3: IDENTIFY — Root Cause Ranking
|
|
182
|
+
count identical commands for loop detection. Produce per-session metrics (duration, tools,
|
|
183
|
+
compactions, test runs, spur calls, guard failures, key finding) plus aggregate totals. Discovery
|
|
184
|
+
roots for the fallback path are in [references/session-formats.md](references/session-formats.md).
|
|
185
|
+
|
|
186
|
+
### Phase 2: IDENTIFY — Root Cause Ranking
|
|
195
187
|
|
|
196
188
|
**Goal:** Rank bottlenecks by estimated time cost; apply topic / category / severity filters.
|
|
197
189
|
|
|
@@ -223,7 +215,7 @@ Before any ad-hoc verification SQL against `history_*` tables, follow the schema
|
|
|
223
215
|
|
|
224
216
|
Also note **what worked well** so efficient patterns are preserved.
|
|
225
217
|
|
|
226
|
-
### Phase
|
|
218
|
+
### Phase 3: PROPOSE — Fix Design
|
|
227
219
|
|
|
228
220
|
**Goal:** Design a concrete fix for each **in-scope** root cause.
|
|
229
221
|
|
|
@@ -245,9 +237,10 @@ When the same anti-pattern appears across **≥2 independent sessions** (or the
|
|
|
245
237
|
codify it), offer a handoff to **`/sp:rule-scan`** / rule authoring after GENERATE — do not invent
|
|
246
238
|
rules inside this skill.
|
|
247
239
|
|
|
248
|
-
### Phase
|
|
240
|
+
### Phase 4: GENERATE — Task File Creation
|
|
249
241
|
|
|
250
|
-
**Goal:** Create a structured task via CLI-gated corpus writes (
|
|
242
|
+
**Goal:** Create a structured task via CLI-gated corpus writes (`--create-task` only; default
|
|
243
|
+
mode stops after the report).
|
|
251
244
|
|
|
252
245
|
**Task creation (correct CLI — do not invent flags):**
|
|
253
246
|
|
|
@@ -258,25 +251,15 @@ spur task create "Fix <context> performance bottlenecks: <top issues>" \
|
|
|
258
251
|
--json
|
|
259
252
|
```
|
|
260
253
|
|
|
261
|
-
Notes:
|
|
262
|
-
|
|
263
254
|
- Title is the **positional** argument (there is no `--name`).
|
|
264
255
|
- Template is space form `--template meta` (or `issue` / `standard`); never the dotted form.
|
|
256
|
+
- Single-finding tasks: prefer `--template issue`; multi-requirement umbrella: keep `meta`.
|
|
265
257
|
- Priority is **not** available on create. After create:
|
|
266
258
|
|
|
267
259
|
```bash
|
|
268
260
|
spur task update <wbs> --priority P2 --json
|
|
269
261
|
```
|
|
270
262
|
|
|
271
|
-
- If `--feature` was omitted at create time and the operator later supplies one:
|
|
272
|
-
|
|
273
|
-
```bash
|
|
274
|
-
spur task update <wbs> --feature <feature-id> --json
|
|
275
|
-
```
|
|
276
|
-
|
|
277
|
-
- Single-finding tasks: prefer `--template issue` (aligned with `sp:sys-debugging`).
|
|
278
|
-
- Multi-requirement umbrella: keep `--template meta` (default).
|
|
279
|
-
|
|
280
263
|
**Section population** — write each section body to a temp file, then:
|
|
281
264
|
|
|
282
265
|
```bash
|
|
@@ -304,7 +287,7 @@ spur task update <wbs> --section Background --from-file /tmp/issue-bg.md --json
|
|
|
304
287
|
**Section format rules** (from task 0379):
|
|
305
288
|
|
|
306
289
|
1. **Solution `file:line` citations**: repo-relative `file:line` (e.g. `apps/web/src/components/SupervisorTab.tsx:17-20`), never bare `:line` or bare filename without path.
|
|
307
|
-
2. **Review P1–P4 table**: if a Review section exists, include a
|
|
290
|
+
2. **Review P1–P4 table**: if a Review section exists, include a table with a cell matching
|
|
308
291
|
`/^\s*P[1-4]\s*$/` and a non-placeholder content cell.
|
|
309
292
|
3. **Meta template**: no `Root Cause` section — put analyses in `Notes`.
|
|
310
293
|
4. **Canonical sections only**: `Background`, `Requirements`, `Acceptance Criteria`, `Q&A`,
|
|
@@ -324,10 +307,12 @@ Must return `pass: true` with 0 errors. Warnings may be acceptable on meta tasks
|
|
|
324
307
|
|
|
325
308
|
## Output
|
|
326
309
|
|
|
327
|
-
**Default:**
|
|
328
|
-
|
|
310
|
+
**Default:** markdown report on stdout — the 8 CLI-derivable forensics sections (when the data
|
|
311
|
+
plane path applies) plus the model-authored IDENTIFY/PROPOSE analysis.
|
|
329
312
|
|
|
330
|
-
**With `--
|
|
313
|
+
**With `--create-task`:** a task file under the configured tasks folder (`docs/tasks/`,
|
|
314
|
+
`docs/tasks3/`, …) with WBS, optional feature link, and structured sections, plus a short summary
|
|
315
|
+
with the WBS.
|
|
331
316
|
|
|
332
317
|
**With `--json`:**
|
|
333
318
|
|
|
@@ -351,42 +336,36 @@ WBS, optional feature link, and structured sections.
|
|
|
351
336
|
}
|
|
352
337
|
```
|
|
353
338
|
|
|
354
|
-
|
|
355
|
-
|
|
339
|
+
With `--create-task`, include `"task": { "wbs": "…", "file": "…", "status": "…" }`; otherwise
|
|
340
|
+
`task` stays `null`.
|
|
356
341
|
|
|
357
342
|
## Integration
|
|
358
343
|
|
|
359
|
-
- **Session
|
|
344
|
+
- **Session forensics report** — `spur history report --mode forensics` (primary data plane)
|
|
360
345
|
- **Multi-source roots / field maps** — [references/session-formats.md](references/session-formats.md)
|
|
361
|
-
- **
|
|
346
|
+
- **Raw JSONL fallback** — only under the three conditions in Phase 1
|
|
362
347
|
- **`spur task create` / `update` / `check`** — CLI-gated corpus only (never direct-write task files)
|
|
363
348
|
|
|
364
349
|
## Required Permissions
|
|
365
350
|
|
|
366
|
-
| Capability | Purpose
|
|
367
|
-
| --------------- |
|
|
368
|
-
| `Read` | Session JSONL, skill/source files
|
|
369
|
-
| `Grep` / `Glob` | Pattern search and session discovery
|
|
370
|
-
| `Bash` | `spur
|
|
371
|
-
| `Write` | Temp files for section bodies
|
|
351
|
+
| Capability | Purpose |
|
|
352
|
+
| --------------- | ------------------------------------ |
|
|
353
|
+
| `Read` | Session JSONL, skill/source files |
|
|
354
|
+
| `Grep` / `Glob` | Pattern search and session discovery |
|
|
355
|
+
| `Bash` | `spur history` + `spur task` CLI |
|
|
356
|
+
| `Write` | Temp files for section bodies |
|
|
372
357
|
|
|
373
358
|
## Platform Notes
|
|
374
359
|
|
|
375
|
-
|
|
376
|
-
|
|
377
|
-
|
|
378
|
-
-
|
|
379
|
-
|
|
380
|
-
|
|
381
|
-
|
|
382
|
-
-
|
|
383
|
-
|
|
384
|
-
- If the agent’s session root differs from the table in session-formats.md, require `--sessions`.
|
|
385
|
-
|
|
386
|
-
### Multi-agent reality
|
|
387
|
-
|
|
388
|
-
- Packaging is portable; **forensic fidelity is source-dependent**.
|
|
389
|
-
- When unsure of layout, ask once for a session path or use `--sessions` rather than guessing.
|
|
360
|
+
- **Claude Code** — invoke via `/sp:dev-find-issue …` or `Skill(skill="sp:issue-finding",
|
|
361
|
+
args="…")`. Prefer structured tools for file discovery; parse JSONL with Read/Grep only on the
|
|
362
|
+
fallback path.
|
|
363
|
+
- **Other platforms** (Codex / OpenClaw / OpenCode / Antigravity / Pi) — follow the 4-phase
|
|
364
|
+
protocol (slash commands may be adapted at install time); prefer `rg` for large JSONL on the
|
|
365
|
+
fallback path. If the agent's session root differs from the session-formats.md table, require
|
|
366
|
+
`--sessions`.
|
|
367
|
+
- **Multi-agent reality** — packaging is portable; **forensic fidelity is source-dependent**. When
|
|
368
|
+
unsure of layout, ask once for a session path or use `--sessions` rather than guessing.
|
|
390
369
|
|
|
391
370
|
## Shipped command
|
|
392
371
|
|
|
@@ -398,38 +377,41 @@ Thin wrapper: `Skill(skill="sp:issue-finding", args="$ARGUMENTS")`.
|
|
|
398
377
|
/sp:dev-find-issue
|
|
399
378
|
/sp:dev-find-issue "test-loop spinning"
|
|
400
379
|
/sp:dev-find-issue --sessions "~/.omp/agent/sessions/-xprojects-spur-new/2026-07-29T*" --feature H51
|
|
401
|
-
/sp:dev-find-issue
|
|
402
|
-
/sp:dev-find-issue --
|
|
380
|
+
/sp:dev-find-issue --category test-loop,guard
|
|
381
|
+
/sp:dev-find-issue --create-task "J4 batch bottlenecks" --template meta --priority P1
|
|
403
382
|
/sp:dev-find-issue --json --source claude --since 2026-07-28
|
|
404
383
|
```
|
|
405
384
|
|
|
406
385
|
## Common rationalizations
|
|
407
386
|
|
|
408
|
-
| Rationalization
|
|
409
|
-
|
|
|
410
|
-
| "Sessions are huge — I'll sample randomly."
|
|
411
|
-
| "I
|
|
412
|
-
| "
|
|
413
|
-
| "
|
|
414
|
-
| "
|
|
387
|
+
| Rationalization | Reality |
|
|
388
|
+
| -------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
|
|
389
|
+
| "Sessions are huge — I'll sample randomly." | Prefer signal Grep first, then deep-read hot regions. Random samples invent severity. |
|
|
390
|
+
| "I must hand-parse JSONL for everything." | The typed data plane renders 8 sections. Raw parsing is only for the three fallback conditions. |
|
|
391
|
+
| "I'll just write the task file with Write." | Corpus writes are CLI-gated (`spur task create` / `update`). Direct Write fails the harness contract. |
|
|
392
|
+
| "OMP format everywhere." | Only OMP is High-fidelity documented. Other sources need portable field maps + `--sessions` when roots differ. |
|
|
393
|
+
| "P0 severity means task priority P0." | Severity (S0–S2) ranks waste; `--priority` is separate task frontmatter (P0–P3). |
|
|
394
|
+
| "The CLI report is the whole deliverable." | The renderer emits data; the model-authored IDENTIFY/PROPOSE analysis makes it actionable. |
|
|
415
395
|
|
|
416
396
|
## Red flags
|
|
417
397
|
|
|
398
|
+
- Creating a task without `--create-task` (default mode is report-only).
|
|
399
|
+
- Wholesale raw JSONL parsing when the source has a typed mapper.
|
|
400
|
+
- Accepting `--use-history` or `--no-task` silently instead of naming their replacements.
|
|
418
401
|
- GENERATE recipes inventing a title flag, dotted template forms, or quoted dotted section flags.
|
|
419
402
|
- Claiming multi-agent forensics without stating source confidence (High/Medium/Low).
|
|
420
|
-
-
|
|
421
|
-
- Skipping batch section writes + single `spur task check`.
|
|
403
|
+
- Skipping batch section writes + single `spur task check` (when generating).
|
|
422
404
|
- Emitting empty findings without inventorying sessions first.
|
|
423
405
|
|
|
424
406
|
## Dogfood / self-check fixture
|
|
425
407
|
|
|
426
408
|
A tiny synthetic OMP session lives under
|
|
427
409
|
[examples/session-test-loop.jsonl](examples/session-test-loop.jsonl) with expected categories in
|
|
428
|
-
[examples/expected-findings.json](examples/expected-findings.json). Use it to smoke-check
|
|
429
|
-
without real operator logs:
|
|
410
|
+
[examples/expected-findings.json](examples/expected-findings.json). Use it to smoke-check the
|
|
411
|
+
fallback parser without real operator logs (explicit `--sessions` is fallback condition 2):
|
|
430
412
|
|
|
431
413
|
```
|
|
432
|
-
/sp:dev-find-issue --sessions plugins/sp/skills/issue-finding/examples/session-test-loop.jsonl
|
|
414
|
+
/sp:dev-find-issue --sessions plugins/sp/skills/issue-finding/examples/session-test-loop.jsonl
|
|
433
415
|
```
|
|
434
416
|
|
|
435
417
|
Expect at least the `test-loop` category (and whatever else the expected-findings file lists).
|
|
@@ -23,5 +23,5 @@
|
|
|
23
23
|
"minCompactions": 6
|
|
24
24
|
}
|
|
25
25
|
],
|
|
26
|
-
"smokeCommand": "/sp:dev-find-issue --sessions plugins/sp/skills/issue-finding/examples/session-test-loop.jsonl
|
|
26
|
+
"smokeCommand": "/sp:dev-find-issue --sessions plugins/sp/skills/issue-finding/examples/session-test-loop.jsonl"
|
|
27
27
|
}
|