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 2026-03-05 16:18:24 +01:00
parent 4d829ff47d
commit 52d12a28b7
11 changed files with 837 additions and 17 deletions

View file

@ -6,6 +6,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
## [Unreleased]
## [3.30.2] - 2026-03-05
### Documentation
- **Conductor section enriched** (`guide/third-party-tools.md:376`) — section rewritten from 5 generic bullets to 6 structured subsections, verified against official changelog (conductor.build). Added: workspace status system (backlog → done, v0.35.0), Next Workspace button for agent queue navigation (v0.36.4), turn-by-turn diff viewer (v0.22.0), Manual Mode built-in editor replacing VSCode for quick edits (v0.37.0), full GitHub/CI integration details (Actions tab v0.33.2, failing CI → Claude auto-fix v0.12.0, PR workflow with `⌘⇧P`), Linear deeplinks, Codex support alongside Claude, Melty Labs attribution. Community workflow pattern added: 5+ parallel features across multiple repos, BMAD + Conductor combo for spec-driven development (user-reported, unverified claim clearly marked).

View file

@ -6,7 +6,7 @@
<p align="center">
<a href="https://github.com/FlorianBruniaux/claude-code-ultimate-guide/stargazers"><img src="https://img.shields.io/github/stars/FlorianBruniaux/claude-code-ultimate-guide?style=for-the-badge" alt="Stars"/></a>
<a href="./CHANGELOG.md"><img src="https://img.shields.io/badge/Updated-Mar_4,_2026_·_v3.30.1-brightgreen?style=for-the-badge" alt="Last Update"/></a>
<a href="./CHANGELOG.md"><img src="https://img.shields.io/badge/Updated-Mar_5,_2026_·_v3.30.2-brightgreen?style=for-the-badge" alt="Last Update"/></a>
<a href="./quiz/"><img src="https://img.shields.io/badge/Quiz-274_questions-orange?style=for-the-badge" alt="Quiz"/></a>
<a href="./examples/"><img src="https://img.shields.io/badge/Templates-176-green?style=for-the-badge" alt="Templates"/></a>
<a href="./guide/security-hardening.md"><img src="https://img.shields.io/badge/🛡_Threat_DB-24_CVEs_·_655_malicious_skills-red?style=for-the-badge" alt="Threat Database"/></a>
@ -846,7 +846,7 @@ See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.
---
*Version 3.30.1 | Updated daily · Mar 4, 2026 | Crafted with Claude*
*Version 3.30.2 | Updated daily · Mar 5, 2026 | Crafted with Claude*
<!-- SEO Keywords -->
<!-- claude code, claude code tutorial, anthropic cli, ai coding assistant, claude code mcp,

View file

@ -1 +1 @@
3.30.1
3.30.2

View file

@ -0,0 +1,76 @@
# Resource Evaluation: Boris Paillard — "Son site custom en 2h avec Claude Code"
**Date**: 2026-03-05
**Source**: [LinkedIn Pulse](https://www.linkedin.com/pulse/son-site-custom-en-2h-avec-claude-code-m%C3%A9thodes-et-prompts-paillard-7q8je/)
**Type**: Tutorial / Workflow walkthrough
**Author**: Boris Paillard — ex-Le Wagon instructor, co-founder mixt.care
**Score**: 3/5
---
## Summary
Workflow for building a custom website in ~2h using Claude Code, centered on a "design-first" approach. Core thesis: Claude Code executes your design taste — it doesn't replace it. You must define a design system before prompting, or every generated page drifts.
Four-step method with concrete prompts published in the article:
1. **brand-book.html** — color palette with semantic roles, fonts, CSS variables
2. **ui-kit.html** — base components documented with Tailwind CSS
3. **Full site development** — scroll animations, sticky images, statement footers
4. **Conditional forms** (bonus) — JSON-driven multi-step forms with Google Apps Script
Concrete project: mixt.care (personalized dermatology). Stack: Tailwind CSS + vanilla JS (Intersection Observer).
---
## Score Justification
**3/5 — Relevant, integrate as field example.**
The four-step methodology is structurally sound and the 4 prompts are specific and usable. The core insight (HTML reference files as persistent Claude Code context) is not documented in the guide and is genuinely reusable.
However: no WCAG/accessibility coverage, no differentiation from Cursor/Copilot, no GitHub repo to verify results, and no discussion of maintainability past the MVP. The guide's technical sections need more rigorous sources.
---
## Gap Identified → Action Taken
**Gap**: The guide had no documentation of the "Design Reference File" pattern — keeping `brand-book.html` and `ui-kit.html` at the project root as permanent context files for Claude Code. This pattern ensures design coherence across all generated pages without re-prompting.
**Action**: Added `examples/claude-md/design-reference-file.md` — a standalone template for the pattern, with:
- Recommended project structure
- CLAUDE.md snippet to activate automatic design system reference
- Prompt for brand-book.html with WCAG audit embedded
- Prompt for ui-kit.html documentation
- Color audit prompt (WCAG 2.1 compliance, color blindness simulation, fix suggestions)
No changes to `ultimate-guide.md` — the pattern is documented as an example, not promoted to a guide section. Score does not justify central placement.
---
## What the Article Does NOT Cover
- WCAG accessibility / contrast ratios for the generated palette
- Maintainability after the 2h MVP (technical debt, component evolution)
- Why Claude Code specifically vs. Cursor or Copilot
- No GitHub repo or live code to verify the claimed output
---
## Fact-Check
| Claim | Status |
|-------|--------|
| Author: Boris Paillard | Confirmed — LinkedIn byline |
| Date: March 5, 2026 | Confirmed — `datePublished: 2026-03-05T08:14:35Z` |
| Project: mixt.care (dermatology) | Confirmed — mentioned explicitly |
| 2h timeframe | Confirmed — title + body |
| Font sizes: 6rem desktop / 3rem mobile | Confirmed — in footer prompt |
| Animations: 0.6s + 100ms stagger | Confirmed — in Intersection Observer prompt |
| 4 prompts published in article | Confirmed — verified on second fetch |
| "Co-founder Le Wagon" | Correction — article says "launched a workshop 10 years ago", not co-founder |
---
## Decision
**Integrate as field example.** The "Design Reference File" pattern (brand-book.html + ui-kit.html as permanent project context) is the one novel, reusable insight. Extract as a standalone example template. Do not cite as a primary technical source.

View file

@ -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)

View 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: h1h4, 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

View 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 3090 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 (3090d): {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.550.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.

View 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*
```

View file

@ -12,7 +12,7 @@ tags: [cheatsheet, reference]
**Written with**: Claude (Anthropic)
**Version**: 3.30.1 | **Last Updated**: February 2026
**Version**: 3.30.2 | **Last Updated**: February 2026
---
@ -613,4 +613,4 @@ where.exe claude; claude doctor; claude mcp list
**Author**: Florian BRUNIAUX | [@Méthode Aristote](https://methode-aristote.fr) | Written with Claude
*Last updated: February 2026 | Version 3.30.1*
*Last updated: February 2026 | Version 3.30.2*

View file

@ -16,7 +16,7 @@ tags: [guide, reference, workflows, agents, hooks, mcp, security]
**Last updated**: January 2026
**Version**: 3.30.1
**Version**: 3.30.2
---
@ -4946,7 +4946,7 @@ The `.claude/` folder is your project's Claude Code directory for memory, settin
| Personal preferences | `CLAUDE.md` | ❌ Gitignore |
| Personal permissions | `settings.local.json` | ❌ Gitignore |
### 3.30.1 Version Control & Backup
### 3.30.2 Version Control & Backup
**Problem**: Without version control, losing your Claude Code configuration means hours of manual reconfiguration across agents, skills, hooks, and MCP servers.
@ -22508,4 +22508,4 @@ We'll evaluate and add it to this section if it meets quality criteria.
**Contributions**: Issues and PRs welcome.
**Last updated**: January 2026 | **Version**: 3.30.1
**Last updated**: January 2026 | **Version**: 3.30.2

View file

@ -3,7 +3,7 @@
# Source: guide/ultimate-guide.md
# Purpose: Condensed index for LLMs to quickly answer user questions about Claude Code
version: "3.30.1"
version: "3.30.2"
updated: "2026-03-03"
# ════════════════════════════════════════════════════════════════
@ -883,6 +883,14 @@ deep_dive:
pr_triage_phases: "3 (audit + deep review + validated comments)"
pr_triage_when: "5+ open PRs, periodic backlog triage, post-sprint cleanup"
pr_triage_vs_review_pr: "pr-triage = backlog N PRs | review-pr = single PR focus"
# Issue Triage Skill (added 2026-03-05)
issue_triage_skill: "examples/skills/issue-triage/SKILL.md"
issue_triage_template: "examples/skills/issue-triage/templates/issue-comment.md"
issue_triage_phases: "3 (audit + deep analysis + validated actions)"
issue_triage_when: "10+ open issues, periodic backlog cleanup, duplicate detection"
issue_triage_jaccard: "Jaccard similarity >= 0.60 on normalized title+body tokens — self-contained, no external lib"
issue_triage_thresholds: "staleness_days=30, very_stale_days=90, jaccard_threshold=60%, closed_compare=20, open_limit=100"
issue_triage_vs_pr_triage: "issue-triage = issue backlog (comment/label/close) | pr-triage = PR backlog (code review comment)"
# Cowork documentation (v1.0 - migrated to dedicated repo)
cowork_reference: "machine-readable/cowork-reference.yaml" # Dedicated YAML index (kept local)
cowork_hub: "https://github.com/FlorianBruniaux/claude-cowork-guide/blob/main/README.md"
@ -1438,7 +1446,7 @@ ecosystem:
- "Cross-links modified → Update all 4 repos"
history:
- date: "2026-01-20"
event: "Code Landing sync v3.30.1, 66 templates, cross-links"
event: "Code Landing sync v3.30.2, 66 templates, cross-links"
commit: "5b5ce62"
- date: "2026-01-20"
event: "Cowork Landing fix (paths, README, UI badges)"
@ -1450,7 +1458,7 @@ ecosystem:
onboarding_matrix_meta:
version: "2.0.0"
last_updated: "2026-02-05"
aligned_with_guide: "3.30.1"
aligned_with_guide: "3.30.2"
changelog:
- version: "2.0.0"
date: "2026-02-05"
@ -1478,7 +1486,7 @@ onboarding_matrix:
core: [rules, sandbox_native_guide, commands]
time_budget: "5 min"
topics_max: 3
note: "SECURITY FIRST - sandbox before commands (v3.30.1 critical fix)"
note: "SECURITY FIRST - sandbox before commands (v3.30.2 critical fix)"
beginner_15min:
core: [rules, sandbox_native_guide, workflow, essential_commands]
@ -1563,7 +1571,7 @@ onboarding_matrix:
- default: agent_validation_checklist
time_budget: "60 min"
topics_max: 6
note: "Dual-instance pattern for quality workflows (v3.30.1)"
note: "Dual-instance pattern for quality workflows (v3.30.2)"
learn_security:
intermediate_30min:
@ -1574,7 +1582,7 @@ onboarding_matrix:
- default: permission_modes
time_budget: "30 min"
topics_max: 4
note: "NEW goal (v3.30.1) - Security-focused learning path"
note: "NEW goal (v3.30.2) - Security-focused learning path"
power_60min:
core: [sandbox_native_guide, mcp_secrets_management, security_hardening]
@ -1599,7 +1607,7 @@ onboarding_matrix:
core: [rules, sandbox_native_guide, workflow, essential_commands, context_management, plan_mode]
time_budget: "60 min"
topics_max: 6
note: "Security foundation + core workflow (v3.30.1 sandbox added)"
note: "Security foundation + core workflow (v3.30.2 sandbox added)"
intermediate_120min:
core: [plan_mode, agents, skills, config_hierarchy, git_mcp_guide, hooks, mcp_servers]