Lore Workflow

Use this skill when the user asks the AI to write, fix, or clean up in-code comments and docstrings — the clan calls this "lore."

Contents

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

At A Glance

1. Read context/policies/lore-policy.md for the shape rules.
2. Figure out the target: the current diff by default, or a file/PR the user names.
3. For each function/class/module in scope, add a docstring only where the policy calls for one, fix one that's wrong, and strip a comment that violates the policy (states the obvious, stale, decorative).
4. Leave already-compliant lore untouched.
5. Report what changed, file:line. Never commit, push, or open/update a PR — that's ship's job.

What This Is Not

• Not ship: it never stages, commits, or pushes. Run ship afterward to land the lore changes.
• Not roast: it edits code directly instead of posting findings for someone else to fix.
• Not a documentation generator for README/external docs sites — scope is in-source comments and docstrings only.
• Not permission to touch code logic. If a docstring reveals a bug, say so and stop; don't fix the bug as part of this skill unless the user asks.

Trigger Rules

• Run when the user explicitly asks to lore, comment the code, add docstrings, document a function/file, or clean up comments.
• If the target is ambiguous (no file, diff, or PR implied and none is the obvious current work), ask which scope before editing anything.

Requirements

The diff and file targets need nothing beyond local git and file access. The pull request target additionally needs a GitHub MCP connector configured for this session (read access is enough — this skill never posts to GitHub), or gh installed and authenticated as a fallback. Without either, stop and tell the user the PR target isn't reachable and ask whether to use the local diff or a named file instead — don't silently substitute a different scope for the one they asked for.

Prerequisites

• Read context/policies/lore-policy.md. Use the target repo's copy when it exists; otherwise use the bundled copy at ${CLAUDE_PLUGIN_ROOT}/context/policies/lore-policy.md.
• Check git status --short to know what's actually in scope before editing.
• Identify the doc-comment syntax the file/language already uses (JSDoc, Google-style Python, Rustdoc, godoc, etc.) from existing examples in the repo; don't invent a format the codebase doesn't use.

Targets

• Current diff (default) — unstaged and staged changes from git diff / git diff --staged, plus new files reported as untracked by git status --short (git diff alone won't show them). Scope lore edits to the functions, classes, and modules the diff actually touches or adds.
• File(s) — when the user names a file or path, scope to that file only.
• Pull request — when the user names a PR, fetch its diff through the GitHub MCP connector (falling back to gh) and scope to the files it touches, applied to the local working tree on that branch.

Default Path

1. Determine the target and read context/policies/lore-policy.md.
2. List the functions/classes/modules in scope.
3. For each: add a docstring if the policy calls for one and none exists, fix one that's inaccurate or missing a non-obvious param, and remove/rewrite any inline comment that restates the code, is stale, or is decorative.
4. Match the existing doc-comment syntax for that language; don't mix conventions within a file.
5. Skip anything already compliant — don't touch it just to reformat it.
6. Report the changes as a file:line list, grouped by file.

Guardrails

• Never commit, push, stage, or touch a PR/issue as part of this skill.
• Never change code behavior — comments and docstrings only.
• Never invent behavior the code doesn't have; ground every docstring in what the function actually does, not what its name suggests it should do.
• Don't add a comment or docstring the policy says to skip (trivial one-liners, self-explanatory signatures) just to raise coverage.

Stop Conditions

• Stop and ask if there's no identifiable target (no diff, no named file, no current work to infer from).
• Stop if a docstring pass reveals the code doesn't do what its name or an existing comment claims — report the mismatch instead of silently "documenting" the bug away.
• Stop if the file's existing doc-comment convention is unclear and no repo example resolves it — ask instead of guessing a format.
• Stop if the user asked for the pull request target and neither the GitHub MCP connector nor gh is available — ask whether to use the diff or a named file instead of silently switching targets.

Handoff

• Unless the user asked for plain output, open with a fresh one-line phrase in the orc voice, speaking as the Loremaster from context/personality.md (the target repo's copy when it exists, otherwise ${CLAUDE_PLUGIN_ROOT}/context/personality.md). If they did, open with the plain result instead.
• List the files touched and a one-line count of what changed (added/fixed/ removed).
• Remind the user that ship is the next step if they want these changes committed.
• 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.

Lore added to a diff:

📜 Hrrm. Etched the missing runes into three new functions. ✨

`src/auth/token.ts`: added 2 docstrings, fixed 1 stale comment.
`src/auth/session.ts`: added 1 docstring.
Run `ship` to carry this into a commit.

Nothing to add:

📜 Hah! The armory's already marked true. Nothing to etch here.

Scanned the current diff — every function already carries accurate lore.

Blocked, no target:

❓ Chief, what should we mark: the current diff, a file, or a PR?