release: v3.30.2 — issue-triage skill, design-reference-file, Conductor docs
New templates: - examples/skills/issue-triage/ — 3-phase issue backlog management with Jaccard duplicate detection, risk classification, and validated actions - examples/claude-md/design-reference-file.md — brand-book + ui-kit pattern for consistent UI generation across sessions Resource evaluation: - docs/resource-evaluations/075-paillard-design-system-first-website.md (Boris Paillard, mixt.care, score 3/5) Docs update: - guide/third-party-tools.md — Conductor section enriched with verified features (Next Workspace, Manual Mode, GitHub CI integration, BMAD pattern) Version bump: 3.30.1 → 3.30.2 (synced across README, cheatsheet, guide, reference.yaml) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Florian BRUNIAUX
parent
4d829ff47d
commit
52d12a28b7
11 changed files with 837 additions and 17 deletions
|
|
@ -17,7 +17,7 @@ Annotated templates that teach you **why** patterns work, not just how to config
|
|||
| [`agents/`](./agents/) | Custom AI personas for specialized tasks | 9 |
|
||||
| [`commands/`](./commands/) | Slash commands (workflow automation) | 26 |
|
||||
| [`hooks/`](./hooks/) | Event-driven security & automation scripts | 31 |
|
||||
| [`skills/`](./skills/) | Reusable knowledge modules — [9 on SkillHub](https://skills.palebluedot.live/owner/FlorianBruniaux) | 14 |
|
||||
| [`skills/`](./skills/) | Reusable knowledge modules — [9 on SkillHub](https://skills.palebluedot.live/owner/FlorianBruniaux) | 15 |
|
||||
| [`claude-md/`](./claude-md/) | CLAUDE.md configuration profiles | 6 |
|
||||
| [`config/`](./config/) | Settings, MCP, git templates | 5 |
|
||||
| [`memory/`](./memory/) | CLAUDE.md memory file templates | 2 |
|
||||
|
|
@ -67,7 +67,7 @@ Annotated templates that teach you **why** patterns work, not just how to config
|
|||
| [implementer.md](./agents/implementer.md) | Mechanical execution — bounded scope | Haiku |
|
||||
| [architecture-reviewer.md](./agents/architecture-reviewer.md) | Architecture & design review — read-only | Opus |
|
||||
|
||||
### Skills (14) — [9 on SkillHub](https://skills.palebluedot.live/owner/FlorianBruniaux)
|
||||
### Skills (15) — [9 on SkillHub](https://skills.palebluedot.live/owner/FlorianBruniaux)
|
||||
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
|
|
@ -85,6 +85,7 @@ Annotated templates that teach you **why** patterns work, not just how to config
|
|||
| [guide-recap/](./skills/guide-recap/) | Transform CHANGELOG entries into social content (LinkedIn, Twitter/X, Slack) |
|
||||
| [release-notes-generator/](./skills/release-notes-generator/) | Generate release notes in 3 formats from git commits |
|
||||
| [pr-triage/](./skills/pr-triage/) | 3-phase PR backlog management (audit, deep review, validated comments) |
|
||||
| [issue-triage/](./skills/issue-triage/) | 3-phase issue backlog management (audit, deep analysis, validated actions) |
|
||||
|
||||
### Commands (26)
|
||||
|
||||
|
|
|
|||
176
examples/claude-md/design-reference-file.md
Normal file
176
examples/claude-md/design-reference-file.md
Normal file
|
|
@ -0,0 +1,176 @@
|
|||
---
|
||||
title: "Design Reference File"
|
||||
description: "Keep brand-book.html and ui-kit.html at project root as permanent Claude Code context for consistent UI generation"
|
||||
tags: [design-system, frontend, web, ui, consistency, brand, color-palette, tailwind]
|
||||
---
|
||||
|
||||
# Design Reference File — CLAUDE.md Pattern
|
||||
|
||||
Keep `brand-book.html` and `ui-kit.html` at the project root as permanent context files. Claude Code reads them before generating any UI — every new page inherits your design system automatically.
|
||||
|
||||
Inspired by Boris Paillard's workflow (mixt.care, March 2026): once the design system is in place, new pages take 5 minutes instead of 30.
|
||||
|
||||
## The Problem
|
||||
|
||||
When building a website with Claude Code across multiple sessions, every new page risks drifting from the design — wrong colors, inconsistent typography, new component variants. Re-stating design constraints in each prompt is repetitive and unreliable.
|
||||
|
||||
## The Solution
|
||||
|
||||
Two HTML files at the project root act as a design memory Claude can read at any time:
|
||||
|
||||
- `brand-book.html` — color palette with semantic roles, fonts, CSS variables, WCAG contrast ratios
|
||||
- `ui-kit.html` — documented components (buttons, forms, trust bars, section labels)
|
||||
|
||||
One CLAUDE.md instruction makes Claude reference them before every UI task.
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
project/
|
||||
├── brand-book.html # Color palette + typography + CSS variables (permanent reference)
|
||||
├── ui-kit.html # Component library documented with Tailwind
|
||||
├── CLAUDE.md # Design system instruction below
|
||||
├── src/
|
||||
│ ├── styles/
|
||||
│ │ └── tokens.css # CSS variables extracted from brand-book.html
|
||||
│ └── components/
|
||||
└── ...
|
||||
```
|
||||
|
||||
## CLAUDE.md Snippet
|
||||
|
||||
Add this to your project-level `CLAUDE.md`:
|
||||
|
||||
```markdown
|
||||
## Design System
|
||||
|
||||
Always read `brand-book.html` and `ui-kit.html` before generating any UI component, page, or layout.
|
||||
|
||||
Rules:
|
||||
- Never hardcode colors or font sizes — use CSS variables from brand-book.html
|
||||
- Reuse components from ui-kit.html before creating new variants
|
||||
- New pages must use the same design tokens (--color-primary, --font-primary, etc.)
|
||||
- If a requested design element is not in the UI kit, document it in ui-kit.html after creating it
|
||||
```
|
||||
|
||||
## Step 1 — Generate brand-book.html
|
||||
|
||||
```
|
||||
Create a brand-book.html file at the project root.
|
||||
|
||||
For each color in my palette, display a card showing:
|
||||
- Color swatch (120×80px block)
|
||||
- Name, hex code, RGB values, HSL values
|
||||
- CSS variable name (e.g. --color-primary)
|
||||
- Semantic role: PRIMARY | DARK | LIGHT | ACCENT | NEUTRAL
|
||||
- Usage rule in plain text (e.g. "CTAs, buttons, active links")
|
||||
- WCAG contrast ratio vs white: X.X:1 — AA PASS/FAIL — AAA PASS/FAIL
|
||||
- WCAG contrast ratio vs black: X.X:1 — AA PASS/FAIL — AAA PASS/FAIL
|
||||
|
||||
My palette:
|
||||
[LIST YOUR COLORS AND ROLES HERE]
|
||||
|
||||
My fonts:
|
||||
[LIST YOUR FONTS HERE]
|
||||
|
||||
Include a type scale section: 12px / 16px / 20px / 24px / 32px / 48px / 64px / 96px with rem equivalents.
|
||||
|
||||
At the bottom, output a copyable <style> block with all CSS variables (:root { ... }).
|
||||
|
||||
Style brand-book.html itself using these variables — it should demonstrate the design system.
|
||||
```
|
||||
|
||||
## Step 2 — Generate ui-kit.html
|
||||
|
||||
```
|
||||
Build ui-kit.html documenting my base components using Tailwind and the CSS variables from brand-book.html.
|
||||
|
||||
Include:
|
||||
- Buttons: primary/secondary/ghost variants, 3 sizes (sm/md/lg)
|
||||
- Trust bars with vertical color separators
|
||||
- Section labels with horizontal rules (uppercase, letter-spacing)
|
||||
- Typography specimens: h1–h4, body, caption — using --font-primary and --font-secondary
|
||||
- Color swatches grid with contrast ratios displayed
|
||||
- Form elements: input, select, textarea in default/focus/error states
|
||||
|
||||
Each component should show: component name, usage notes, and the Tailwind classes used.
|
||||
Reference CSS variables from brand-book.html — no hardcoded values.
|
||||
```
|
||||
|
||||
## Step 3 — WCAG Color Audit (optional but recommended)
|
||||
|
||||
Run this after generating the brand book to catch accessibility issues before building:
|
||||
|
||||
```
|
||||
Audit the color palette in brand-book.html for WCAG 2.1 compliance:
|
||||
|
||||
1. For all likely foreground/background combinations, calculate exact contrast ratios (2 decimal places)
|
||||
2. Flag pairs that fail WCAG AA: 4.5:1 for normal text, 3:1 for large text and UI components
|
||||
3. Simulate deuteranopia, protanopia, tritanopia — flag problematic combinations
|
||||
4. For each failing pair, suggest the minimum hex adjustment to pass AA while staying within 10% hue deviation
|
||||
5. Output: markdown table with columns: Combination | Ratio | AA Normal | AA Large | AAA | Color Blind Safe
|
||||
|
||||
External references:
|
||||
- WebAIM Contrast Checker: https://webaim.org/resources/contrastchecker/
|
||||
- ColorOracle (color blindness simulator): https://colororacle.org/
|
||||
```
|
||||
|
||||
## Step 4 — Scroll Animations (optional)
|
||||
|
||||
```
|
||||
Add scroll animations to all cards and section titles using vanilla JS Intersection Observer.
|
||||
Elements should fade in + slide up with 0.6s ease-out transitions, 100ms stagger between items.
|
||||
Apply only to elements with [data-animate] attribute — opt-in, not global.
|
||||
Do not use any animation library — vanilla JS only.
|
||||
```
|
||||
|
||||
## Example — mixt.care Color Palette
|
||||
|
||||
Well-structured palette with semantic roles and CSS variables:
|
||||
|
||||
```css
|
||||
:root {
|
||||
/* Colors */
|
||||
--color-primary: #5C1A2E; /* Deep bordeaux — CTAs, buttons, active links */
|
||||
--color-dark: #3D2B1F; /* Warm brown — body text, dark backgrounds */
|
||||
--color-accent: #B87333; /* Copper — hover states, secondary highlights */
|
||||
--color-secondary: #6B5B8E; /* Soft violet — badges, illustrations */
|
||||
--color-light: #F5F0EA; /* Cream — section backgrounds, cards */
|
||||
|
||||
/* Typography */
|
||||
--font-primary: 'Geist', sans-serif; /* Body text */
|
||||
--font-secondary: 'Newsreader', serif; /* Emphasis, quotes */
|
||||
--font-display: 'Fraunces', serif; /* Logo, display headings only */
|
||||
|
||||
/* Type scale */
|
||||
--text-xs: 0.75rem;
|
||||
--text-sm: 0.875rem;
|
||||
--text-base: 1rem;
|
||||
--text-lg: 1.25rem;
|
||||
--text-xl: 1.5rem;
|
||||
--text-2xl: 2rem;
|
||||
--text-3xl: 3rem;
|
||||
--text-display: 6rem; /* Desktop statement footer */
|
||||
--text-display-mobile: 3rem;
|
||||
}
|
||||
```
|
||||
|
||||
**WCAG notes for this palette** (estimated):
|
||||
- Bordeaux on cream: ~8.2:1 — AA PASS
|
||||
- Brown on cream: ~9.1:1 — AA PASS
|
||||
- White on bordeaux: ~8.2:1 — AA PASS
|
||||
- Copper on white: ~3.1:1 — AA FAIL for normal text (use only for UI components or darken to #9B5F20)
|
||||
- Violet on cream: ~4.8:1 — AA PASS
|
||||
|
||||
## When to Use This Pattern
|
||||
|
||||
- Building a marketing site, landing page, or product website with Claude Code
|
||||
- When you need consistent design across multiple pages generated in different sessions
|
||||
- Before starting UI work on any project with established brand guidelines
|
||||
- Replacing manual design system documentation with an interactive, self-demonstrating reference
|
||||
|
||||
## Limitations
|
||||
|
||||
- Effective for static/marketing sites and MVPs — complex component libraries need a proper design system tool (Storybook, Figma)
|
||||
- The 2h timeframe assumes you know your design intent before prompting (colors, fonts, layout direction)
|
||||
- WCAG audit from Claude is estimated — verify critical pairs with WebAIM or a dedicated tool
|
||||
450
examples/skills/issue-triage/SKILL.md
Normal file
450
examples/skills/issue-triage/SKILL.md
Normal file
|
|
@ -0,0 +1,450 @@
|
|||
---
|
||||
name: issue-triage
|
||||
description: >
|
||||
3-phase issue backlog management: audit open issues, deep analyze selected ones, draft and execute
|
||||
triage actions with mandatory validation. Args: "all" to analyze all, issue numbers to focus
|
||||
(e.g. "42 57"), "en"/"fr" for language, no arg = audit only in French.
|
||||
tags: [github, issue, triage, maintainer, multi-agent]
|
||||
---
|
||||
|
||||
# Issue Triage
|
||||
|
||||
3-phase workflow for maintainers: automated audit of all open issues, opt-in deep analysis via parallel agents, and validated triage actions (comments, labels, closures).
|
||||
|
||||
## When to Use This Skill
|
||||
|
||||
| Skill | Usage | Output |
|
||||
|-------|-------|--------|
|
||||
| `/issue-triage` | Sort, analyze, and act on an issue backlog | Triage tables + analysis + executed actions |
|
||||
| `/pr-triage` | Sort, review, and comment on a PR backlog | Triage table + reviews + posted comments |
|
||||
|
||||
**Triggers**:
|
||||
- Manually: `/issue-triage` or `/issue-triage all` or `/issue-triage 42 57`
|
||||
- Proactively: when >10 open issues without label, or stale issues >30 days detected
|
||||
|
||||
---
|
||||
|
||||
## Language
|
||||
|
||||
- Check the argument passed to the skill
|
||||
- If `en` or `english` → tables and summary in English
|
||||
- If `fr`, `french`, or no argument → French (default)
|
||||
- Note: GitHub comments and labels (Phase 3) are ALWAYS in English (international audience)
|
||||
|
||||
---
|
||||
|
||||
## Configuration
|
||||
|
||||
Thresholds used throughout the workflow. Edit to match your project:
|
||||
|
||||
| Parameter | Default | Description |
|
||||
|-----------|---------|-------------|
|
||||
| `staleness_days` | 30 | Days without activity before flagging as stale |
|
||||
| `very_stale_days` | 90 | Days without activity before flagging as very stale |
|
||||
| `jaccard_threshold` | 60% | Minimum Jaccard similarity to flag two issues as duplicates |
|
||||
| `closed_compare_count` | 20 | Number of recent closed issues to compare for duplicate detection |
|
||||
| `open_limit` | 100 | Maximum open issues to fetch and analyze |
|
||||
|
||||
---
|
||||
|
||||
## Preconditions
|
||||
|
||||
```bash
|
||||
git rev-parse --is-inside-work-tree
|
||||
gh auth status
|
||||
```
|
||||
|
||||
If either fails, stop and explain what is missing.
|
||||
|
||||
---
|
||||
|
||||
## Phase 1 — Audit (always executed)
|
||||
|
||||
### Data Gathering (parallel commands)
|
||||
|
||||
```bash
|
||||
# Repo identity
|
||||
gh repo view --json nameWithOwner -q .nameWithOwner
|
||||
|
||||
# Open issues (exclude PRs, limit 100)
|
||||
gh issue list --state open --limit 100 \
|
||||
--json number,title,author,createdAt,updatedAt,labels,body,comments,assignees,milestone
|
||||
|
||||
# Recent closed issues (for duplicate detection)
|
||||
gh issue list --state closed --limit 20 \
|
||||
--json number,title,body,labels,stateReason
|
||||
|
||||
# Open PRs (bodies for cross-reference detection)
|
||||
gh pr list --state open --limit 50 --json number,title,body
|
||||
|
||||
# Collaborators (to distinguish reporter types)
|
||||
gh api "repos/{owner}/{repo}/collaborators" --jq '.[].login'
|
||||
```
|
||||
|
||||
**Collaborators fallback**: if `gh api .../collaborators` returns 403/404:
|
||||
```bash
|
||||
# Extract authors from last 10 merged PRs
|
||||
gh pr list --state merged --limit 10 --json author --jq '.[].author.login' | sort -u
|
||||
```
|
||||
If still ambiguous, ask via `AskUserQuestion`.
|
||||
|
||||
**Note**: `comments` field in `gh issue list --json comments` returns the count, not content. For Phase 2, fetch full content separately: `gh issue view {num} --json comments`.
|
||||
|
||||
### Analysis Dimensions
|
||||
|
||||
Run all 6 dimensions for each open issue:
|
||||
|
||||
#### 1. Categorization
|
||||
|
||||
Classify each issue by reading `title` + first 200 chars of `body`:
|
||||
|
||||
| Category | Label | Criteria |
|
||||
|----------|-------|----------|
|
||||
| Bug | `bug` | Describes broken behavior, unexpected output, crash |
|
||||
| Feature Request | `enhancement` | Asks for new functionality |
|
||||
| Question / Support | `question` | User asking how something works |
|
||||
| Documentation | `documentation` | Missing or incorrect docs |
|
||||
| Out of Scope | `wontfix` | Clearly outside project boundaries |
|
||||
| Unclear | `needs-info` | Body empty, too vague to categorize |
|
||||
|
||||
If body is empty → category is always `Unclear` (never assume).
|
||||
|
||||
#### 2. Cross-reference to PRs
|
||||
|
||||
Scan each open PR body for references to the issue number:
|
||||
- Patterns: `fixes #N`, `closes #N`, `resolves #N`, `fix #N`, `close #N` (case-insensitive, `N` = issue number)
|
||||
- Use regex locally on the `body` fields already fetched — do NOT make N additional API calls
|
||||
- If found: flag issue as "PR-linked" with PR number
|
||||
|
||||
#### 3. Duplicate Detection via Jaccard Similarity
|
||||
|
||||
**Algorithm (self-contained — no external library)**:
|
||||
|
||||
For each open issue, compute Jaccard similarity against all other open issues AND the 20 most recent closed issues.
|
||||
|
||||
```
|
||||
Step 1 — Normalize title + first 300 chars of body:
|
||||
- Lowercase the full text
|
||||
- Strip category prefixes: "feat:", "fix:", "bug:", "chore:", "docs:", "test:", "refactor:"
|
||||
- Remove punctuation: .,!?;:'"()[]{}-_/\@#
|
||||
|
||||
Step 2 — Tokenize:
|
||||
- Split on whitespace
|
||||
- Remove stop words: the a an is in on to for of and or with this that it can not no be
|
||||
- Remove tokens shorter than 3 characters
|
||||
|
||||
Step 3 — Compute Jaccard:
|
||||
tokens_A = set of tokens from issue A
|
||||
tokens_B = set of tokens from issue B
|
||||
jaccard = |tokens_A ∩ tokens_B| / |tokens_A ∪ tokens_B|
|
||||
|
||||
Step 4 — Flag:
|
||||
- If jaccard >= 0.60: mark as potential duplicate
|
||||
- Report: "Similar to #N (Jaccard: 0.72)"
|
||||
- Keep the OLDER issue as canonical; newer = duplicate candidate
|
||||
```
|
||||
|
||||
Jaccard is computed at runtime using the fetched data — no API calls beyond Phase 1 gather.
|
||||
|
||||
#### 4. Risk Classification
|
||||
|
||||
Assign Red / Yellow / Green based on signals in title + body:
|
||||
|
||||
| Level | Color | Criteria |
|
||||
|-------|-------|----------|
|
||||
| Critical | Red | Security vulnerability, data loss, regression blocking users, crash in production |
|
||||
| Needs Attention | Yellow | Missing validation, performance degradation, breaking change undocumented, Unclear with no response for >7 days |
|
||||
| Normal | Green | Everything else |
|
||||
|
||||
#### 5. Staleness
|
||||
|
||||
| Status | Criterion |
|
||||
|--------|-----------|
|
||||
| Active | Updated within 30 days |
|
||||
| Stale | No activity 30–90 days |
|
||||
| Very Stale | No activity >90 days |
|
||||
|
||||
Use `updatedAt` field. Staleness does NOT depend on comments count — a commented-on issue with old `updatedAt` is still stale.
|
||||
|
||||
#### 6. Recommendations
|
||||
|
||||
One recommended action per issue:
|
||||
|
||||
| Situation | Action |
|
||||
|-----------|--------|
|
||||
| Category = Unclear, body empty | Comment requesting details |
|
||||
| Jaccard >= 0.60 with known issue | Close as duplicate, link original |
|
||||
| Very stale + no assignee | Comment requesting status, suggest close |
|
||||
| Risk = Red | Pin to top of triage, escalate immediately |
|
||||
| Category = OOS | Close with explanation |
|
||||
| PR-linked | No action needed (tracked via PR) |
|
||||
| Normal + labeled | No action needed |
|
||||
|
||||
### Output — Triage Tables
|
||||
|
||||
```
|
||||
## Open Issues ({count})
|
||||
|
||||
### Critical — Immediate Attention (Risk: Red)
|
||||
| # | Title | Category | Reporter | Days Open | Action |
|
||||
|---|-------|----------|----------|-----------|--------|
|
||||
|
||||
### PR-Linked (tracked in open PRs)
|
||||
| # | Title | Category | PR | Days Open |
|
||||
|---|-------|----------|----|-----------|
|
||||
|
||||
### Active Issues
|
||||
| # | Title | Category | Labels | Reporter | Days | Action |
|
||||
|---|-------|----------|--------|----------|------|--------|
|
||||
|
||||
### Duplicate Candidates
|
||||
| # | Title | Similar To | Jaccard | Action |
|
||||
|---|-------|------------|---------|--------|
|
||||
|
||||
### Stale Issues
|
||||
| # | Title | Category | Last Activity | Reporter | Action |
|
||||
|---|-------|----------|---------------|----------|--------|
|
||||
|
||||
### Summary
|
||||
- Total open: {N}
|
||||
- Critical (Red): {count}
|
||||
- PR-linked: {count}
|
||||
- Duplicate candidates: {count}
|
||||
- Stale (30–90d): {count}
|
||||
- Very stale (>90d): {count}
|
||||
- Unlabeled: {count}
|
||||
- Recommended actions: {comment: N, label: N, close: N}
|
||||
```
|
||||
|
||||
0 issues → display `No open issues.` and stop.
|
||||
|
||||
**Protection rules** (apply to all phases):
|
||||
- Never close an issue authored by a collaborator without explicit user confirmation
|
||||
- Never re-label an issue that already has labels (only add missing labels)
|
||||
- If body is empty → always request details before any other action
|
||||
- Never auto-close a Red issue without user confirmation
|
||||
|
||||
### Automatic Copy
|
||||
|
||||
After displaying the triage tables, copy to clipboard using platform-appropriate command:
|
||||
|
||||
```bash
|
||||
UNAME=$(uname -s)
|
||||
if [ "$UNAME" = "Darwin" ]; then
|
||||
pbcopy <<'EOF'
|
||||
{full triage tables}
|
||||
EOF
|
||||
elif command -v xclip &>/dev/null; then
|
||||
echo "{full triage tables}" | xclip -selection clipboard
|
||||
elif command -v wl-copy &>/dev/null; then
|
||||
echo "{full triage tables}" | wl-copy
|
||||
elif command -v clip.exe &>/dev/null; then
|
||||
echo "{full triage tables}" | clip.exe
|
||||
fi
|
||||
```
|
||||
|
||||
Confirm: `Triage tables copied to clipboard.` (EN) / `Tableaux copiés dans le presse-papier.` (FR)
|
||||
|
||||
---
|
||||
|
||||
## Phase 2 — Deep Analysis (opt-in)
|
||||
|
||||
### Issue Selection
|
||||
|
||||
**If argument passed**:
|
||||
- `"all"` → all issues with recommended actions
|
||||
- Numbers (`"42 57"`) → only those issues
|
||||
- No argument → propose via `AskUserQuestion`
|
||||
|
||||
**If no argument**, display:
|
||||
|
||||
```
|
||||
question: "Which issues do you want to analyze in depth?"
|
||||
header: "Deep Analysis"
|
||||
multiSelect: true
|
||||
options:
|
||||
- label: "All ({N} issues with recommended actions)"
|
||||
description: "Launch parallel analysis agents for each actionable issue"
|
||||
- label: "Critical only ({M} Red issues)"
|
||||
description: "Focus on high-risk issues requiring immediate action"
|
||||
- label: "Duplicate candidates ({K} issues)"
|
||||
description: "Verify Jaccard similarity with full body + comments"
|
||||
- label: "Stale only ({J} stale issues)"
|
||||
description: "Decide which stale issues to close vs. revive"
|
||||
- label: "Skip"
|
||||
description: "Stop here — audit only"
|
||||
```
|
||||
|
||||
If "Skip" → end workflow.
|
||||
|
||||
### Executing Analysis
|
||||
|
||||
For each selected issue, launch an analysis agent via **Task tool in parallel**:
|
||||
|
||||
```
|
||||
subagent_type: general
|
||||
model: sonnet
|
||||
prompt: |
|
||||
Analyze GitHub issue #{num}: "{title}"
|
||||
|
||||
**Metadata**: Category={category}, Risk={risk}, Days open={days}, Labels={labels}
|
||||
**Reporter**: @{author} ({collaborator? "collaborator" : "external"})
|
||||
**Assignees**: {assignees or "none"}
|
||||
|
||||
**Body**:
|
||||
{body}
|
||||
|
||||
**Comments** (fetch via: gh issue view {num} --json comments):
|
||||
{comments[].body — truncate at 5000 chars total}
|
||||
|
||||
**Duplicate candidates**: {jaccard_results or "none found"}
|
||||
**Linked PRs**: {pr_refs or "none"}
|
||||
|
||||
Tasks:
|
||||
1. Verify the category assigned in Phase 1 (correct? suggest alternative if not)
|
||||
2. If duplicate candidate: confirm or deny similarity with rationale
|
||||
3. If Unclear/needs-info: identify exactly what information is missing
|
||||
4. Suggest the most appropriate action with exact text if a comment is needed
|
||||
5. Estimate effort to fix if it's a Bug or Feature Request (XS/S/M/L/XL)
|
||||
|
||||
Return structured output:
|
||||
### Verification
|
||||
### Duplicate Analysis
|
||||
### Missing Information
|
||||
### Recommended Action
|
||||
### Effort Estimate
|
||||
```
|
||||
|
||||
**Fallback if parallel agents unavailable**: run analysis sequentially, one issue at a time. Notify user: `Running sequential analysis (parallel agents not available).`
|
||||
|
||||
Fetch full comments via:
|
||||
```bash
|
||||
gh issue view {num} --json comments --jq '.comments[].body'
|
||||
```
|
||||
|
||||
Aggregate all reports. Display a summary after all analyses complete.
|
||||
|
||||
---
|
||||
|
||||
## Phase 3 — Actions (mandatory validation)
|
||||
|
||||
### Draft Generation
|
||||
|
||||
For each analyzed issue, generate the appropriate action using the template `templates/issue-comment.md`.
|
||||
|
||||
**3 action types**:
|
||||
|
||||
| Type | Command | When |
|
||||
|------|---------|------|
|
||||
| Comment | `gh issue comment {num} --body-file -` | Needs info, stale ping, OOS explanation |
|
||||
| Label | `gh issue edit {num} --add-label "{label}"` | Unlabeled issue with clear category |
|
||||
| Close | `gh issue close {num} --reason "not planned"` | Duplicate, OOS, very stale |
|
||||
|
||||
**Rules**:
|
||||
- Language for comments: **English** (international audience)
|
||||
- Labels added: use existing repo labels only (fetch with `gh label list`)
|
||||
- Close reason: `"not planned"` for OOS/duplicate, `"completed"` only if a fix was merged
|
||||
- Never post a comment AND close in the same action without user seeing both drafts
|
||||
- Always attach a comment when closing (explain why)
|
||||
|
||||
### Display and Validation
|
||||
|
||||
**Display ALL drafted actions** in format:
|
||||
|
||||
```
|
||||
---
|
||||
### Draft — Issue #{num}: {title}
|
||||
|
||||
**Action**: {Comment / Label / Close + Comment}
|
||||
**Reason**: {1 sentence}
|
||||
|
||||
{full comment text if applicable}
|
||||
|
||||
---
|
||||
```
|
||||
|
||||
Then request validation via `AskUserQuestion`:
|
||||
|
||||
```
|
||||
question: "These actions are ready. Which ones do you want to execute?"
|
||||
header: "Execute Triage Actions"
|
||||
multiSelect: true
|
||||
options:
|
||||
- label: "All ({N} actions)"
|
||||
description: "Execute all drafted triage actions"
|
||||
- label: "Issue #{x} — {title_truncated} ({action_type})"
|
||||
description: "Execute only this action"
|
||||
- label: "None"
|
||||
description: "Cancel — execute nothing"
|
||||
```
|
||||
|
||||
(Generate one option per issue + "All" + "None")
|
||||
|
||||
### Execution
|
||||
|
||||
For each validated action:
|
||||
|
||||
```bash
|
||||
# Comment
|
||||
gh issue comment {num} --body-file - <<'TRIAGE_EOF'
|
||||
{comment}
|
||||
TRIAGE_EOF
|
||||
|
||||
# Label
|
||||
gh issue edit {num} --add-label "{label}"
|
||||
|
||||
# Close with comment
|
||||
gh issue comment {num} --body-file - <<'TRIAGE_EOF'
|
||||
{close comment}
|
||||
TRIAGE_EOF
|
||||
gh issue close {num} --reason "not planned"
|
||||
```
|
||||
|
||||
Confirm each action: `Action executed on issue #{num}: {title}`
|
||||
|
||||
If "None" → `No actions executed. Workflow complete.`
|
||||
|
||||
---
|
||||
|
||||
## Edge Cases
|
||||
|
||||
| Situation | Behavior |
|
||||
|-----------|----------|
|
||||
| 0 open issues | Display `No open issues.` + stop |
|
||||
| Body empty | Category = Unclear, action = request details, never assume |
|
||||
| Collaborator as reporter | Protect from auto-close, flag explicitly in table |
|
||||
| Jaccard inconclusive (0.55–0.65) | Flag as "possible duplicate — verify manually" |
|
||||
| Label not in repo | Skip label action, notify user to create the label first |
|
||||
| Issue already closed during workflow | Skip silently, note in summary |
|
||||
| `gh api .../collaborators` 403/404 | Fallback to last 10 merged PR authors |
|
||||
| Parallel agents unavailable | Run sequential analysis, notify user |
|
||||
| Very large body (>5000 chars) | Truncate to 5000 chars with `[truncated]` note |
|
||||
| Milestone assigned | Include in table, never close milestoned issues without confirmation |
|
||||
|
||||
---
|
||||
|
||||
## Notes
|
||||
|
||||
- Always derive owner/repo via `gh repo view`, never hardcode
|
||||
- Use `gh` CLI (not `curl` GitHub API) except for collaborators list
|
||||
- `comments` in `gh issue list --json comments` = count only; full content requires `gh issue view {num} --json comments`
|
||||
- Never execute any action without explicit user validation in chat
|
||||
- Drafted actions must be visible BEFORE any `gh issue comment` or `gh issue close`
|
||||
- Jaccard is computed locally — no external API, no library, pure set operations on fetched data
|
||||
- Signature on all comments: `*Triaged via Claude Code /issue-triage*`
|
||||
|
||||
---
|
||||
|
||||
## Related: /pr-triage
|
||||
|
||||
| | `/issue-triage` | `/pr-triage` |
|
||||
|--|----------------|--------------|
|
||||
| **Scope** | Issue backlog | PR backlog |
|
||||
| **Use when** | Catching up on reporter feedback, periodic issue cleanup | Catching up after PR accumulation |
|
||||
| **Phases** | 3 (audit + deep analysis + actions) | 3 (audit + deep review + comments) |
|
||||
| **Agents** | Parallel sub-agents per issue | Parallel sub-agents per PR |
|
||||
| **Duplicate detection** | Jaccard similarity on title+body | File overlap % between PRs |
|
||||
| **Actions** | Comment / label / close | GitHub review comment |
|
||||
| **Validation** | AskUserQuestion before executing | AskUserQuestion before posting |
|
||||
|
||||
**Decision rule**: use `/issue-triage` for issue backlog management, `/pr-triage` for code review backlog.
|
||||
107
examples/skills/issue-triage/templates/issue-comment.md
Normal file
107
examples/skills/issue-triage/templates/issue-comment.md
Normal file
|
|
@ -0,0 +1,107 @@
|
|||
# Issue Comment Templates
|
||||
|
||||
Use these templates to generate GitHub issue comments during `/issue-triage` Phase 3. Comments are posted in **English** (international audience).
|
||||
|
||||
---
|
||||
|
||||
## Template 1 — Ack / Info Request
|
||||
|
||||
Use when: issue is `Unclear` or `needs-info`, body is missing context, reproduction steps are absent.
|
||||
|
||||
```markdown
|
||||
Thanks for opening this issue!
|
||||
|
||||
To help us investigate, could you provide the following?
|
||||
|
||||
- **Steps to reproduce**: A minimal sequence of actions that triggers the behavior
|
||||
- **Expected behavior**: What you expected to happen
|
||||
- **Actual behavior**: What actually happened
|
||||
- **Environment**: OS, version, relevant config (if applicable)
|
||||
|
||||
Once we have this information, we can prioritize and route the issue appropriately.
|
||||
|
||||
---
|
||||
*Triaged via Claude Code /issue-triage*
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Template 2 — Duplicate
|
||||
|
||||
Use when: Jaccard similarity >= 60% with an existing open or recently closed issue.
|
||||
|
||||
```markdown
|
||||
Thanks for reporting this! After reviewing the backlog, this appears to be a duplicate of #{original_number}.
|
||||
|
||||
{original_number} is tracking the same underlying behavior: {one-sentence description of original}.
|
||||
|
||||
I'm closing this issue to consolidate discussion there. If you believe this is a distinct issue with different root cause or scope, please reopen with additional context explaining the difference.
|
||||
|
||||
---
|
||||
*Triaged via Claude Code /issue-triage*
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Template 3 — Close Stale
|
||||
|
||||
Use when: issue has had no activity for >90 days and no assignee, or no response to a previous info request for >30 days.
|
||||
|
||||
```markdown
|
||||
This issue has been inactive for {days} days without updates or response.
|
||||
|
||||
We're closing it to keep the backlog actionable. If this is still relevant to you, please reopen and provide:
|
||||
|
||||
- Current status: is this still reproducible?
|
||||
- Any additional context or workarounds you've found
|
||||
|
||||
We're happy to pick this back up if it's still blocking you.
|
||||
|
||||
---
|
||||
*Triaged via Claude Code /issue-triage*
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Template 4 — Close Out of Scope
|
||||
|
||||
Use when: issue describes functionality clearly outside the project's stated scope.
|
||||
|
||||
```markdown
|
||||
Thanks for the suggestion! After review, this falls outside the current scope of this project.
|
||||
|
||||
{Briefly explain why — e.g., "This project focuses on X; Y is handled by Z" or "This would require changes to the underlying architecture that are not planned."}
|
||||
|
||||
You might find what you're looking for in:
|
||||
- {alternative project or tool if known}
|
||||
- {documentation link if relevant}
|
||||
|
||||
Feel free to open a discussion if you'd like to explore this further.
|
||||
|
||||
---
|
||||
*Triaged via Claude Code /issue-triage*
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Formatting Rules
|
||||
|
||||
**Tone**: Professional, direct, respectful. The reporter invested time to file the issue.
|
||||
|
||||
**Rules**:
|
||||
- Never imply the reporter is wrong or wasted time
|
||||
- Be specific when referencing duplicates (title + number, not just number)
|
||||
- For close stale: always invite to reopen — do not make it feel permanent
|
||||
- For OOS: offer an alternative when possible, even if vague
|
||||
- No superlatives ("great issue", "awesome report") — factual only
|
||||
|
||||
**Customization points** (replace in all templates):
|
||||
- `{original_number}`: issue number of the canonical duplicate
|
||||
- `{one-sentence description}`: short summary of the original issue
|
||||
- `{days}`: days since last activity (from `updatedAt`)
|
||||
- Inline explanations marked with `{...}`: always fill before posting
|
||||
|
||||
**Signature** (required on all comments):
|
||||
```
|
||||
*Triaged via Claude Code /issue-triage*
|
||||
```
|
||||
Loading…
Add table
Add a link
Reference in a new issue