Triage
Triage insights into actionable GitHub issues across repos. Use after running /insights to convert analysis into tracked work.From its SKILL.md
npx -y skills add rmzi/portable-dev-system --skill triageAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
2 things to look at
- no licenseNo license file was found in the repository. Code published without one is not open source by default, so using it at work is a question for whoever answers licensing questions where you are.
- 24 stars24 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
SKILL.md
10.2 KB, as published. Nobody here has run it
/triage — Insights Triage
Reads Claude Code /insights output (report + facets + session-meta), analyzes each section systematically, and creates GitHub issues across repos with confirmation at every step.
Mode
Plan mode with interactive confirmation. Enter plan mode (EnterPlanMode) before starting. Phases 1-3 are automated data gathering. Phases 4-5 are interactive — the agent proposes, the user confirms. No issues are created without explicit approval.
Model: Use Opus for analysis (heavy-tier reasoning). The cross-referencing and issue-grouping logic benefits from maximum capability.
Prerequisites
/insightshas been run (~/.claude/usage-data/report.htmlexists)ghCLI is authenticated (gh auth status)- Repos referenced in session-meta have git remotes
Invocation
/pds:triage # Full triage of latest insights
/pds:triage --section friction # Triage only the friction section
/pds:triage --repo <name> # Triage for one repo only
/pds:triage --dry-run # Analyze and propose but don't create issues
Protocol
Phase 1: Load
-
Verify insights data exists:
test -f ~/.claude/usage-data/report.html && echo "report found" || echo "MISSING — run /insights first" ls ~/.claude/usage-data/facets/*.json 2>/dev/null | wc -l ls ~/.claude/usage-data/session-meta/*.json 2>/dev/null | wc -lIf report is missing, abort: "Run
/insightsfirst to generate the report." -
Check report freshness:
stat -f '%Sm' -t '%Y-%m-%d' ~/.claude/usage-data/report.htmlIf older than 24 hours, warn: "Report is N days old. Consider re-running
/insightsfor fresh data." -
Check
ghauthentication:gh auth status 2>&1 | head -3If not authenticated, abort: "Run
gh auth loginfirst." -
Load deduplication history:
cat ~/.config/pds/insights/*/manifest.json 2>/dev/nullBuild fingerprint set from all prior
issues_createdentries.
Phase 2: Parse
-
Read report.html. Extract content from each section by HTML id:
Section ID Name Actionability Issue Category section-workWhat You Work On Context (informational) section-usageHow You Use Claude Code Medium workflow-improvementsection-winsImpressive Things You Did Context (reinforcement) section-frictionWhere Things Go Wrong High friction,dx-improvementsection-featuresExisting CC Features to Try High claude-md-update,feature-gapsection-patternsNew Ways to Use Claude Code Medium workflow-improvementsection-horizonOn the Horizon Medium enhancement -
Build repo index. Read session-meta files and build mapping:
project_path → { repo: "owner/name", sessions: N, friction_score: N }Resolution rules:
- Strip
/.worktrees/<anything>suffix (including deeper subdirs) to get base repo path - Run
git -C <path> remote get-url origin 2>/dev/nullfor each unique base path - Parse
owner/repofrom remote URL (handlesgit@andhttps://formats) - Cache the mapping — do not re-resolve within the same run
Filter out:
- Observer sessions (
/.claude-mem/in path) - Bare directories (no
.git) - External volumes (
/Volumes/) - Repos with fewer than 2 sessions
- Strip
-
Join facets to repos. For each facet, look up
session_idin session-meta to get the repo. Aggregate per repo:- Total friction score (sum of
friction_countsvalues) - Top friction types
- Outcome distribution (fully/mostly/partially/not achieved)
- Goal categories
- Total friction score (sum of
-
Present summary to user:
Insights loaded: N analyzed sessions across M repos Top repos by friction: 1. owner/repo-a (43 sessions, friction: 39) 2. owner/repo-b (31 sessions, friction: 42) 3. owner/repo-c (22 sessions, friction: 21) Report sections: 7 (3 high-actionability, 2 medium, 2 context-only) Prior triage runs: K (J issues already created)
Phase 3: Analyze
For each actionable section (friction, features, patterns, horizon), cross-reference with per-repo facet aggregation:
-
Friction section: Match each friction category to repos where it occurs most. Use
friction_detailfrom facets as evidence. Propose groupings — multiple friction points for same root cause become one issue. -
Features section: Map each CLAUDE.md suggestion and feature recommendation to the repos where the friction was observed. Group CLAUDE.md additions into a single checklist issue per repo.
-
Patterns section: Map each workflow pattern to repos/sessions that would benefit.
-
Horizon section: Map capability suggestions to repos where they'd have highest impact. Label as
enhancement.
Phase 4: Section Walk-Through (Interactive)
For each actionable section, present findings and ask for confirmation. One section at a time, no skipping.
For each section:
-
Present analysis with evidence:
## Friction: Wrong Approach Requiring Repeated Redirection Evidence: 38 occurrences across sessions Top repos: owner/repo-a (12), owner/repo-b (8), owner/repo-c (6) Examples from your sessions: - "Claude tried to instantiate providers hitting AWS..." - "Claude started executing code instead of working in plan mode..." Proposed action: Create CLAUDE.md rules in affected repos to constrain behavior. -
Ask the user:
- "Should this become an issue? (yes / no / modify)"
- "Which repos? (all affected / specific subset)"
- "What priority? (high / medium / low)"
-
Wait for response before advancing to next item.
Phase 5: Issue Creation (Interactive)
After all sections are triaged, present the consolidated issue list grouped by repo:
## Proposed Issues
### owner/repo-a
1. [friction] "Add pattern-mirroring constraint to CLAUDE.md" — high
2. [friction] "Add environment preflight check for worktrees" — medium
3. [feature-gap] "Update CLAUDE.md with async job polling rules" — high
### owner/repo-b
4. [workflow] "Add plan-mode enforcement rule" — medium
Create all? (yes / review each / skip)
For each confirmed issue:
-
Pre-create labels if needed:
gh label create "insights-triage" --repo owner/repo --color "7057ff" --force 2>/dev/null gh label create "<category>" --repo owner/repo --color "<color>" --force 2>/dev/null -
Create issue:
gh issue create --repo "owner/repo" --title "<title>" \ --label "insights-triage,<category>" \ --body "$(cat <<'EOF' ## Source Generated by `/pds:triage` from Claude Code `/insights` (DATE). ## Category CATEGORY_NAME ## Evidence - FRICTION_DETAIL or examples from report - N sessions affected, friction score: M ## Suggested Action ACTION_DESCRIPTION --- *Auto-generated by [PDS](https://github.com/rmzi/portable-dev-system) `/triage`* EOF )"
Labels:
| Label | Color | Applied When |
|---|---|---|
insights-triage | #7057ff | Always (identifies PDS-generated issues) |
friction | #d73a4a | From friction section |
dx-improvement | #0075ca | Developer experience improvements |
claude-md-update | #e4e669 | Needs CLAUDE.md changes |
workflow-improvement | #0e8a16 | Process/workflow changes |
enhancement | #a2eeef | Future capability items |
If --dry-run was passed: Complete Phases 1-4 but skip Phase 5. Still save analysis.json in Phase 6.
Phase 6: Persist
-
Create persistence directory:
TRIAGE_DIR=~/.config/pds/insights/$(date +%Y-%m-%d) mkdir -p "$TRIAGE_DIR"If directory exists (same-day re-run), append timestamp:
YYYY-MM-DDTHHMMSS. -
Copy report snapshot:
cp ~/.claude/usage-data/report.html "$TRIAGE_DIR/report.html" -
Write
analysis.json— the aggregated per-repo data from Phase 3. -
Write
manifest.json— issue creation record for deduplication:{ "run_date": "ISO-8601", "report_hash": "sha256 of report.html", "issues_created": [ { "repo": "owner/repo", "number": 42, "title": "...", "category": "friction", "insight_sections": ["section-friction"], "fingerprint": "sha256(title+category+repo)" } ], "issues_skipped": [], "repos_analyzed": 15, "session_count": 214 } -
Print summary:
Triage complete. - N issues created across M repos - K items skipped (already tracked or deferred) - Saved to ~/.config/pds/insights/YYYY-MM-DD/
Rules
- Never create issues without user confirmation. Every issue requires explicit yes.
- Never modify CLAUDE.md directly. Propose changes as issues; the user applies them.
- Deduplicate aggressively. Check prior manifests AND
gh issue list --searchbefore proposing. - One section at a time. Walk through sequentially — do not batch-present all sections.
- Filter noise. Exclude observer sessions, bare directories, repos with <2 sessions.
- Respect
--dry-run. Complete analysis but skip issue creation. Still persist analysis.
Files Read
| File | Purpose |
|---|---|
~/.claude/usage-data/report.html | Insights report (7 sections) |
~/.claude/usage-data/facets/*.json | Per-session analysis (goals, friction, outcomes) |
~/.claude/usage-data/session-meta/*.json | Session metadata (project_path, tools, languages) |
~/.config/pds/insights/*/manifest.json | Prior triage manifests for deduplication |
Files Written
| File | Purpose |
|---|---|
~/.config/pds/insights/YYYY-MM-DD/report.html | Report snapshot |
~/.config/pds/insights/YYYY-MM-DD/analysis.json | Aggregated per-repo analysis |
~/.config/pds/insights/YYYY-MM-DD/manifest.json | Issue creation record |
See Also
/pds:grill— The interrogation pattern this skill adapts/pds:bugfix— For friction items that are actual bugs