report-friction

What this skill does

<!-- Governing: ADR-0015 (Markdown-Native Configuration) -->

# Report Friction with the SDD Plugin

This is a meta-skill: when an SDD plugin skill burns time, breaks, or guides you wrong, you can use this to file a feedback issue against the plugin's own repository (`joestump/claude-plugin-sdd`). The user always sees and approves the entire submission first.

## When to use this skill

This skill is for **significant** friction with the SDD plugin specifically — not minor wobbles, not the user's own code, not third-party tools. The threshold is real cost: tokens wasted, work duplicated, instructions that misled. Use it sparingly.

### Examples that QUALIFY (file an issue)

- A `/sdd:plan` invocation said "use the canonical Branch Naming pattern from references/shared-patterns.md", but that section described a slug algorithm that produced branch names rejected by the tracker. You had to manually fix every branch name.
- `/sdd:work` instructed you to broadcast `FILE_CLAIM` via `SendMessage`, but the agent harness rejected the call because no Team was active. The SKILL.md did not mention that Team initialization was a prerequisite. You spent ~8k tokens debugging.
- `/sdd:check` told you to scan for "the first `# ` heading" to extract titles, but four files in the corpus had a leading H1 in a comment block, causing wrong titles in every report. SKILL.md should specify "first H1 outside frontmatter and outside HTML/comment blocks."
- The same skill failed three times in a row with the same error message. The error came from the skill's own logic, not from the user's environment.

### Examples that DO NOT qualify (don't file)

- A single tool returned an unexpected error and you adapted easily — that's normal operation.
- The user's environment was missing a CLI the skill assumed (e.g., `gh`). That belongs in the user's setup, not as a plugin issue, *unless* the SKILL.md should have done a preflight check and didn't.
- You disagreed with a SKILL.md design choice but it worked correctly. Use `/sdd:adr` to propose a change instead.
- You hit a one-off race condition that you couldn't reproduce. File only if you can describe the trigger.
- The user explicitly asked you to do something the skill warned against, and friction resulted from that. That's the user's call to make, not a plugin bug.

## Process

### Step 1: Preflight — verify gh CLI is available and authenticated

Run these checks in order. If any fails, stop and report the specific remediation.

1. `command -v gh >/dev/null 2>&1` — if missing, output: "The `gh` CLI is not installed. Install from https://cli.github.com/ and re-run." Stop.
2. `gh auth status 2>&1` — if not authenticated, output: "`gh` is not authenticated. Run `gh auth login` and re-run." Stop.
3. Verify network access to the SDD repo: `gh repo view joestump/claude-plugin-sdd --json name >/dev/null 2>&1`. If this fails, the user lacks read access to the repo OR the network is down. Output: "Cannot reach `joestump/claude-plugin-sdd` via gh. Check network and that your GitHub account can read the repo." Stop.

### Step 2: Self-evaluate against the qualification threshold

Before drafting, evaluate the friction against the "When to use this skill" criteria above. If it does not clearly qualify, output a one-line note ("Friction did not meet the report threshold — proceeding without filing.") and stop. The threshold is intentionally high; over-filing dilutes signal in the issue tracker.

A useful self-check: "If the maintainer reads this and asks 'why did the agent file this?', is the answer obviously a plugin defect, not a user error or a one-off?"

### Step 3: Draft the issue body using the canonical template

Use the **Friction Report** template from `references/issue-authoring.md` § Body Templates. The template defines seven sections: Friction summary, Affected, What the SKILL.md said vs. what happened, Reproduction context, Workaround used, Estimated cost, Suggested fix (optional).

The "Said vs. Happened" section is the load-bearing one — it gives the maintainer the diff between intent and observed reality. Without it, a friction report is just a complaint. Be honest with severity: "low / I lost ~2k tokens but worked around it" is useful signal; inflating to "high" because you were frustrated is not. Omit "Suggested fix" if you don't have a concrete one — half-baked suggestions are worse than none.

Fill every applicable section. Don't pad.

### Step 4: Determine labels

Two labels go on every issue this skill files:

1. **`skill-friction`** — auto-applied to every issue. Lets the maintainer filter all friction reports cleanly.
2. **One of**: `bug` / `documentation` / `enhancement` / `usability`. Pick based on what you observed:
   - `bug` — SKILL.md instructions produced wrong behavior (the skill is broken)
   - `documentation` — SKILL.md was correct but ambiguous, missing context, or contradictory (the skill works if you guess right)
   - `enhancement` — the skill was missing a capability you needed (the skill is incomplete)
   - `usability` — the skill worked correctly but burned tokens unnecessarily (the skill is inefficient)

If `$ARGUMENTS` contains `--label <name>`, use that as the second label and skip the auto-classification.

### Step 5: Sanitization scan and redaction

Before showing the draft to the user, scan the body for sensitive content, **replace each match with a clear placeholder**, and keep a record of every redaction. The user sees the sanitized body (which is what will be submitted) plus an explicit "what was redacted" list — so they know both what's leaving the machine and what was changed.

The patterns to detect and the placeholder formats are defined canonically in `references/issue-authoring.md` § Sanitization. Brief recap (see the reference for the full table and rationale):

- Absolute paths under `/Users/`, `/home/`, `/var/`, `/opt/`, `C:\Users\` → `[REDACTED-PATH]/{basename}` (preserve trailing filename)
- URLs containing `internal`, `corp`, `staging`, `dev.`, `.local`, or non-public TLDs → `[REDACTED-URL]`
- Credential-shaped strings near keywords (`token`, `key`, `secret`, `password`, `bearer`) → `[REDACTED-CREDENTIAL]`
- Email addresses on non-public domains → `[REDACTED-EMAIL]`
- IP addresses → `[REDACTED-IP]`

After scanning, you have:

1. A **sanitized body** — the version that will actually be submitted. All placeholders in place, structure preserved.
2. A **redaction log** — a short list naming what was redacted and where (e.g., `Line 12: 1 absolute path → [REDACTED-PATH]`).

When you present the prompt to the user (Step 7), show:

- The **sanitized body in full** (this is the actual submission)
- The redaction log above or below it, clearly labelled "I sanitized N items before showing you this draft"
- An explicit option for the user to choose "edit then submit" if they want to put any redacted content back (the original values are NOT cached — by design, redaction is destructive; the user can re-add specific values if they decide a particular path or URL was actually safe to share)

This balances two goals: sensitive content does not leak even by inattention, AND the user has full visibility into what's leaving the machine. False positives are acceptable; the user can always edit to put something back.

### Step 6: Duplicate search

Run a search against the SDD repo's existing issues:

```bash
gh issue list --repo joestump/claude-plugin-sdd --state all \
  --search "{first 4-6 distinctive words from the friction summary}" \
  --json number,title,state,url --limit 5
```

Surface the top 3 results to the user. If a near-match exists (semantic match on title or summary), include "comment on existing" as a prompt option (Step 7).

### Step 7: User prompt — show the entire submission

Use `AskUserQuestion` with the full proposed issue rendered inline. The question text MUST include the *complete* body (not a summary), the labels that will be applied, and any sanitization warnings. Options:

1.