Imported from joelhooks/joelclaw (skills/signal-friction-scan/SKILL.md). Install upstream with npx skills add joelhooks/joelclaw --skill signal-friction-scan. Copyright stays with the author.

Signal Friction Scan

Use this to turn recent session history into a grounded shortlist of improvements: skill patches, new skills, docs, runbooks, commands, monitors, automations, or deliberate skips.

This is a scan and synthesis skill, not a license to mutate the system immediately. Default to Pass 1: investigate, produce a shortlist, and stop unless Joel explicitly asks to create or patch assets.

When to Use

Trigger on requests like:

• "scan friction"
• "find repeated workflows"
• "what should we package?"
• "look at recent sessions"
• "find missing skills"
• "turn recent work into skills"
• "what keeps pissing me off?"
• "capture the signal/friction scan process"
• "find prompt/system skill improvements from recent work"

Also use it when a task asks for repeated patterns across recent Codex/Pi work, especially if the output should become durable process.

Evidence Order

Use available evidence in this order:

1. Local session signals and friction scans.
2. Targeted session searches and bounded extracts for high-signal hits.
3. Existing skills and docs, to avoid duplicates.
4. .brain/, vault, ADRs, project docs, and swarm memory when relevant.
5. Source repos, logs, issue trackers, Slack/email/task systems only when needed to verify a candidate.

Chronicle or GUI history is discovery-only. Confirm important details in source systems before recommending mutations.

Core Commands

Start with local machine facts:

hostname
pwd

Run the broad signal scan:

joelclaw sessions signals \
  --kind any \
  --source local \
  --machine "$(hostname -s)" \
  --since 30d \
  --limit 40 \
  --evaluate

Run a focused friction scan:

joelclaw sessions friction \
  --source local \
  --machine "$(hostname -s)" \
  --since 30d \
  --limit 30

If hostname -s does not match the machine id used by session capture, rerun with the observed machine id from recent session paths or known context, for example:

joelclaw sessions signals --kind any --source local --machine blaine-the-mono --since 30d --limit 40 --evaluate

Use targeted searches to triangulate themes:

Use recall and the current session-search contract. Keep private queries in structured MCP arguments. Raw evidence requires a scope-bound evidenceDrilldownReceipt; missing projections do not grant raw access.

Inspect existing skill coverage:

find ~/Code/joelhooks/joelclaw/skills -maxdepth 2 -name SKILL.md -print
find ~/Code/joelhooks/joelclaw/skills -maxdepth 2 -name SKILL.md -print \
  | xargs rg -n "friction|signals|workflow-pattern|mode-mismatch|<candidate-term>"

Use bounded extracts only for candidates that may become concrete work:

Use recall and the current session-search contract. Keep private queries in structured MCP arguments. Raw evidence requires a scope-bound evidenceDrilldownReceipt; missing projections do not grant raw access.

How to Read Signals

Treat sessions signals as radar, not truth.

Look at:

• evaluation.bySurface: where improvements are likely to land.
• evaluation.byKind: decision, friction, workflow-pattern, praise, correction, preference.
• evaluation.byReviewPriority: high-priority candidates first.
• clusters: repeated problem classes.
• hits[].improvement: proposed surface, target, confidence, and reason.
• transcript paths, line numbers, dates, and exact user turns.

Do not overfit on single words. Joel's fuck, fucking, and fuckin are emphasis, not automatically anger. Classify by nearby critique, correction, approval, or preference.

Common high-value surfaces:

• skill: repeated procedural failure or missing operating method.
• system-prompt: cross-cutting response shape, action bias, voice, or boundary issue.
• docs: project-local instructions, runbooks, or source summaries.
• memory: durable decision or reusable preference.
• adr: architecture/process decision that should be ratified.
• harness: tool availability, permissions, or runtime mismatch.

Candidate Criteria

Only recommend packaging when most of these are true:

• repeated at least twice, or clearly likely to recur and costly to repeat
• stable inputs
• repeatable procedure
• clear output or stopping condition
• material improvement to speed, quality, consistency, reliability, or discoverability
• not already adequately covered
• validation is possible
• scope can stay narrow

Skip candidates that are one-off, speculative, too broad, mostly taste, private-sensitive, poorly evidenced, or already covered well enough.

Existing Asset Check

Before proposing a new skill, inspect for existing coverage:

• canonical skills in ~/Code/joelhooks/joelclaw/skills
• project-local .pi/skills, .agents/skills, and .brain
• scripts, CLIs, Inngest functions, monitors, GitHub Actions
• ADRs, runbooks, and project docs

Prefer extend existing over creating a duplicate. New skills are for missing reusable workflows, not every interesting pattern.

Output Shape

For Pass 1, return only a shortlist and recommendations. Do not edit files.

Use this shape:

**Evidence Inspected**

- Commands run and notable counts.
- Existing assets checked.
- Sources unavailable or failed.

**Shortlist**

| Candidate | Evidence | Frequency / Confidence | Pain | Recommended Form | Existing Assets | Recommendation |
|---|---|---:|---:|---|---|---|

**Highest-Confidence Recommendations**

1. <candidate>
   Why:
   Scope:
   Validation:

**Deliberately Skipped**

- <candidate and reason>

**Needs More Evidence**

- <candidate and exact missing evidence>

**Validation Performed**

- No files modified, unless explicitly requested.
- Commands run and their results.

Keep the report compact. Lead with the useful answer, then receipts.

Pass 2 Creation Rules

Only create or patch assets when Joel explicitly asks for Pass 2 or asks to capture a specific candidate.

When creating:

• Use the smallest form: patch existing skill/doc before creating new.
• Keep the artifact narrow, source-aware, and easy to validate.
• Do not include raw transcript dumps.
• Do not capture secrets, private overlays, paid corpus text, or irrelevant machine config.
• Include exact commands and fallback behavior where possible.
• Run validation commands or explain why no validation exists.
• Inspect git status --short first and preserve unrelated user work.

For a new joelclaw skill, follow add-skill: create under ~/Code/joelhooks/joelclaw/skills/<name>, keep frontmatter name matching the directory, symlink only where needed, record durable workflow decisions in Brain .svx, and commit only if Joel asks or the current workflow requires it.

Failure Handling

• If joelclaw sessions signals emits huge output or times out after useful JSON, use the emitted counts/clusters and say it timed out.
• Do not depend on the retired slog journal. Use OTel for runtime evidence and Brain .svx for durable receipts.
• If local machine session capture is thin, search Typesense or the relevant remote machine via session-search.
• If evidence is thin, say the evidence is thin. Do not fabricate patterns.