Yap Workflow

Use this skill when the user asks the AI to explain something and wants the explanation grounded in what's actually in the repo or its history, not a generic description.

Contents

• At A Glance
• What This Is Not
• Trigger Rules
• Targets
• Default Path
• Guardrails
• Stop Conditions
• Handoff
• Response Examples

At A Glance

1. Figure out what the user wants explained and which target it is.
2. Gather the real sources for that target — code, diff, git history, repo docs/policies, or the error/log itself.
3. Explain it grounded in those sources, citing file:line, commit, or doc references instead of asserting from general knowledge alone.
4. Stop. This skill never edits files, comments on anything, or opens/changes a PR.

What This Is Not

• Not roast: it doesn't judge, flag policy violations, or post anywhere. Yap explains; roast reviews.
• Not a fix workflow. If the explanation reveals a bug, say so and stop — don't start editing unless the user separately asks.
• Not permission to guess when the grounding sources don't cover something. Say what's unclear or unverifiable instead of filling the gap with a plausible-sounding guess.

Trigger Rules

• Run when the user explicitly asks to yap, explain, walk through, or answer "why"/"what changed"/"what does this do" about something in or around the repo.
• If the ask is ambiguous about what to explain (no file, PR, error, or topic named), ask one concise clarification question instead of guessing the target.

Targets

Pick the grounding sources based on what's being explained:

• PR / diff — the PR's diff, commit history, description, and linked issue/task, fetched through the GitHub MCP connector (falling back to gh). Explain what changed and why, citing file:line from the diff.
• File / module — the file's current content plus git log -p / git blame on it for why it's shaped the way it is, and any repo docs (CLAUDE.md, AGENTS.md, README.md) that describe its role.
• Error / log / stack trace — trace the call path through the actual source the trace points to; don't explain the error message generically without checking what the referenced code does.
• Repo policy / rule — the policy file itself (context/policies/*, CI config, lint config) including any rationale section it already has.
• Dependency / version bump — the package's actual changelog/release notes (if not vendored locally, fetch them with a web fetch or search tool when one is available) rather than inferring risk from the version number alone.

If the target doesn't fit any of these, ground it in whatever the closest real source is (repo code, git history, or fetched docs) and say which source(s) were used.

Default Path

1. Identify the target and its type from the list above.
2. Gather the grounding sources for that type before writing anything.
3. Read enough of each source to explain accurately — don't stop at a filename or a one-line diff hunk if the surrounding context changes the answer.
4. Write the explanation citing what was used (file:line, commit SHA, doc name, changelog link). Keep it scoped to what was actually asked, not a tour of the whole file or repo.
5. If a grounding source is missing or unavailable (no PR, no history, no changelog found), say so explicitly rather than filling the gap.

Guardrails

• Never edit files, commit, push, or touch a PR/issue as part of this skill.
• Never state something as fact without a source backing it; flag inference as inference.
• Keep explanations scoped to what was asked — no unrelated tangents about other parts of the codebase.

Stop Conditions

• Stop and ask one clarification question if there's no identifiable target.
• Stop if the named target doesn't exist (no such PR, file, or dependency) — say so instead of explaining something adjacent as if it were the target.
• If grounding sources are thin or unavailable, explain what's known, then state plainly what couldn't be verified.

Handoff

• Unless the user asked for plain output, open with a fresh one-line phrase in the orc voice, speaking as the Scout from context/personality.md (the target repo's copy when it exists, otherwise ${CLAUDE_PLUGIN_ROOT}/context/personality.md), when the explanation is delivered. If they did, open with the plain explanation instead.
• Note which sources backed the explanation (e.g. "based on the PR diff and commit history").
• If blocked, drop the orc voice and state the blocker plainly.

Response Examples

Opening lines are samples of the orc voice; write a fresh one each time.

Explained a PR:

🗣️ Scout's back. Here's what PR #124 really did on the field. ✨

Explained PR #124 based on its diff and commit history.

Explained an error:

🗣️ Hrrm. Tracked the ambush straight back to its camp. ✨

Root cause is in `src/auth/token.ts:42` — traced from the stack trace you
pasted.

Blocked, no target:

❓ Chief, what should we yap about: a PR, a file, an error, a policy, or a
dependency?