Data-Wise Brainstorm Insights
Aggregate session facet data into a friction/goals report. Pure analysis —
reads ~/.claude/usage-data/facets/*.json, writes a report. Never touches
CLAUDE.md (that's insights-apply's job) and never generates BRAINSTORM/SPEC
documents (that's the brainstorm skill's job — see "Split history" below).
Split history
This skill used to bundle two unrelated operations: ideation (topic +
project/git context → BRAINSTORM-*.md / SPEC-*.md) and session-facet
friction analysis (~/.claude/usage-data/facets/*.json → friction/goals
report). They shared no input and no output, so ideation moved to its own
skills/workflow/brainstorm/. This directory kept the brainstorm-insights
name rather than renaming to session-insights, to avoid a path break for
existing references (references/insights.md — folded from a command into
this skill in the v4 consolidation, Phase 3.5, 2026-07-12 — the dogfood/e2e
scaffold-default tests, insights-apply, and references/scaffold-templates.md
which is shared with orchestrate). Only the Insights operation remains here.
Boundary With Adjacent Skills
| Skill | Role |
|---|---|
| brainstorm-insights (this) | Aggregates session facet history into a friction/goals report |
insights-apply |
Reads INSIGHTS report, writes suggestions into ~/.claude/CLAUDE.md via sync pipeline |
brainstorm |
Generates BRAINSTORM/SPEC documents from topic + context — unrelated input/output, was previously bundled here |
adhd-workflow |
Produces the facet data this skill consumes; also session boundary ops (done, recap, next, focus, stuck, spec-review) |
Chain: adhd-workflow (done) → facets → brainstorm-insights (this) → report → insights-apply → updated CLAUDE.md.
If the user wants to apply insight suggestions to CLAUDE.md, hand off to insights-apply. This skill stops at the report. If the user wants to brainstorm a new idea or capture a spec, hand off to brainstorm.
Inputs
~/.claude/usage-data/facets/*.json— written byadhd-workflow(session done operation).--since N(days, default 30).--project NAME(optional filter).--format terminal|html|json.
Defensive Parsing Contract
Facet files can be malformed (interrupted writes, hand-edits, disk corruption). Every per-file read MUST wrap in try / except catching (json.JSONDecodeError, KeyError, TypeError, FileNotFoundError, UnicodeDecodeError, OSError), log warning: skipping malformed facet <path>: <ErrType>: <msg> to stderr, and continue. Never abort the whole report on a single bad facet. This contract is shared with /craft:hub and /craft:do and is regression-tested in tests/test_facet_parsing_defensive.py.
Aggregation
Across the time window, extract:
- Session count + outcome distribution — success / partial / abandoned.
- Goal categories — feature dev, bug fix, docs, refactoring, other.
- Friction patterns by type:
wrong_approach,context_loss,tool_misuse,test_failure,dependency_issue,config_drift. - Top friction details — specific recurring incidents ("Wrong CWD — 8 times").
claude_md_additions— structured suggestions for CLAUDE.md rules that would prevent the observed friction. Each hastitle,content,priority(high|medium|low),source(which events generated it).
Friction Type → Guardrail Map
When an ORCHESTRATE plan downstream consumes insights, friction types map to guardrails:
| Friction | Guardrail Rule |
|---|---|
wrong_approach |
"Verify CWD is the worktree before starting" |
context_loss |
"Read ORCHESTRATE file on session start" |
tool_misuse |
"Use /craft:do for routing, not manual commands" |
test_failure |
"Run tests after each phase, not just at the end" |
dependency_issue |
"Check package versions match before implementing" |
config_drift |
"Run validate-counts after structural changes" |
Output Formats
- terminal (default) — craft box-drawing report with bar charts, top friction list, and
claude_md_additionssummary. Footer points atinsights-applyskill for next step. - html —
~/.claude/usage-data/report.htmlwith interactive charts, filterable session table, copy-buttons on suggestions. - json — stdout, structured for scripting (
period,sessions,goals,friction,claude_md_additions).
No Data Case
If ~/.claude/usage-data/facets/ is empty or missing, print a short note explaining facets are written automatically by session-done; do not error.
Data Flow
adhd-workflow (done) ──► facets/*.json ──► brainstorm-insights (this) ──► report + claude_md_additions
│
▼
insights-apply skill
│
▼
~/.claude/CLAUDE.md
Integration
Replaced the /craft:insights command (formerly /craft:workflow:insights)
during the v2.34.0 → v3.0.0 migration; folded into this skill in the v4
consolidation (2026-07). No slash-command path remains — ask naturally
("generate insights report").
Test-plan scaffolding (default-on, shared template reference)
This skill's friction reports are not themselves BRAINSTORM/SPEC artifacts,
but it shares the test-plan and Documentation scaffolding contract with the
brainstorm skill and orchestrate, since downstream consumers
(plan-orchestrator) read both this skill's friction map and brainstorm's
scaffolded test plans together. When a SPEC consuming this skill's friction
data is generated (by brainstorm), a test-plan scaffold is emitted by
default. Pass --no-tests to suppress the section.
Tier-inference rule
Infer tiers from the shape of the artifact/change being scoped:
| Change shape | Tiers to emit |
|---|---|
| Flag / frontmatter / prose only | e2e + dogfood |
| + new parser or script | + unit |
| + cross-command data flow | + integration |
| + external dependency change | + dependency |
| + new command / skill / agent | + count-cascade dogfood |
Unselected tiers print as N/A — <reason> (never empty stubs).
Emission rules
- Emit test stubs red-first (failing placeholder, not passing no-op).
- Each stub carries
# TODO(author): delete if not contract-bearinguntil the author confirms the contract. - Scaffold templates live in
references/scaffold-templates.md(this directory) — shared withbrainstormandorchestrate; point to that file, do not duplicate templates inline.
--yes non-suppression
--yes auto-accepts prompts only; the test-plan and Documentation sections are CONTENT and are still emitted under --yes. Only --no-tests/--no-docs remove them.
Opt-out
--no-tests suppresses the entire test-plan section. Default is on.
Documentation scaffolding (default-on)
When this skill emits a BRAINSTORM or SPEC artifact, it also emits a Documentation section by default. Pass --no-docs to suppress the section.
Which docs to emit
Derive which documentation artifacts are needed by running the existing doc-scorer rubric from skills/orchestration/references/doc-impact-rubric.md (threshold ≥3). Do not invent a new rubric — reuse the scorer as the single source of truth.
For each doc type the scorer evaluates (guide, refcard, demo, mermaid), pre-check ([x]) boxes that meet the threshold, and mark the rest N/A — score <N>. The template for the Documentation section lives in references/scaffold-templates.md.
Lifecycle split
| Phase | Action |
|---|---|
| Spec-time | Read-only emit + pre-derive: render the Documentation section with pre-checked boxes. No file edits. |
| Impl/post-merge | Real edits via /craft:docs:update --post-merge. Diff-confirm gated before applying. |
Count-cascade exclusion
Auto-docs emission touches only semantic docs — CHANGELOG [Unreleased] ×2 mirror, guide/refcard/tutorial prose. It never touches version or count lines. Version/count updates stay in bump-version.sh.
Opt-out
--no-docs suppresses the entire Documentation section. Default is on.
Related Skills
insights-apply— consumes this skill's report, writes suggestions to CLAUDE.md. Do not duplicate that logic here.adhd-workflow— produces the facet data this skill consumes.brainstorm— unrelated operation; was previously bundled with this skill, now separate atskills/workflow/brainstorm/.plan-orchestrator— consumes friction data from this skill alongside brainstorm-generated specs.