feat(claude): add /article-audit slash command for external-knowledge auditing#87
Merged
Merged
Conversation
…icles to CLAUDE.md Operationalizes the routine I've been doing ad-hoc all session: paste an article, get a comparison table against existing rule encoding, decide in one glance — covered, divergent, or genuine gap. The routine produced issues #85 (consumer-idempotency patterns) and #86 (sidecar reconsideration triggers); this command makes it reusable so it doesn't depend on remembering the procedure each time. ## Procedure encoded 1. Read the article (URL → WebFetch, or pasted) 2. Extract 5–10 load-bearing claims 3. Map each against CLAUDE.md / .coderabbit.yaml / architecture-reviewer Pattern Checklist / .claude/skills/ / supporting docs 4. Classify: already-encoded-stricter / already-encoded-equivalent / considered-and-rejected / encoded-but-not-consolidated / implicit-worth-making-explicit / genuine-gap 5. Output comparison table + verdict + (if action warranted) draft issue body ready for `gh issue create` ## Style - Tight (user is checking if article is worth their attention) - Quote canonical CLAUDE.md wording exactly (paraphrase = drift) - Don't auto-open issues — ask first - Don't recommend issues for trivial restatements ## Usage - `/article-audit <URL>` — fetch + audit - `/article-audit pasted` — audit content in prior message - `/article-audit` (no args) — audit the most recent pasted article ## Why a command, not a skill Per .claude/README.md decision tree: recurring motion → slash command. The procedure is a multi-step audit applied repeatedly, not specialized domain knowledge worth loading on demand. Lives next to /check-rules, /sync-status, /new-feature-slice — same audit-motion category. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
WalkthroughAdded ChangesArticle Audit Command Documentation
Estimated code review effort🎯 2 (Simple) | ⏱️ ~15 minutes 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In @.claude/commands/article-audit.md:
- Around line 141-147: The repository's slash-command inventory/docs are missing
the new /article-audit command; update the slash-command tables and any command
inventory documentation to include /article-audit with a short description and
the three example invocations shown (full-URL fetch, "pasted", and no-args
behavior), and ensure any index or README that lists available slash commands
reflects this addition so discoverability and workflow guidance remain accurate.
- Around line 19-24: Update the input contract text to make `$ARGUMENTS`
optional and explicitly document the no-arg invocation behavior: state that if
no arguments are provided the command will use the user's previous message as
the article body (same behavior as the literal `pasted` case), otherwise treat
`$ARGUMENTS` as either a URL (fetch via `WebFetch`), the literal word `pasted`
(use prior message body), or the article text itself. Ensure the later lines
that currently unconditionally instruct "run using `$ARGUMENTS`" are changed to
reflect this optionality and point to the three cases above (`WebFetch`,
`pasted`, or raw article text) so the semantics are consistent across the
document.
- Around line 44-61: Add docs/STATUS.md to the audit's mapped surfaces so the
audit checks deferrals/status before recommending work: update the ordered
search list (the block that currently enumerates `/CLAUDE.md`,
`.coderabbit.yaml` `path_instructions`,
`.claude/agents/architecture-reviewer.md`, `.claude/skills/dotnet-performance/`,
and the "Supporting docs" list) to include `docs/STATUS.md` (preferably checked
immediately after the "Supporting docs" group or before proposing issues) and
ensure the audit logic that enumerates these surfaces references the new
`docs/STATUS.md` entry so deferrals are discovered before recommending new
tasks.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro Plus
Run ID: 45b41fff-e64f-425f-90be-a22357f0ed0f
📒 Files selected for processing (1)
.claude/commands/article-audit.md
Comment on lines
+19
to
+24
| `$ARGUMENTS` is one of: | ||
| - A URL → fetch it with `WebFetch`, then audit the content | ||
| - The literal word `pasted` → the article body is in the user's previous | ||
| message; audit that | ||
| - Something else → assume it's the article body itself, audit it | ||
|
|
There was a problem hiding this comment.
Align input contract with no-arg invocation behavior.
Line 19-24 defines $ARGUMENTS as required forms, but Line 145-146 documents valid no-arg usage; Line 148 then unconditionally says to run using $ARGUMENTS. This ambiguity can produce incorrect execution when args are empty.
Proposed doc fix
## Inputs
-`$ARGUMENTS` is one of:
+`$ARGUMENTS` is one of:
- A URL → fetch it with `WebFetch`, then audit the content
- The literal word `pasted` → the article body is in the user's previous
message; audit that
- Something else → assume it's the article body itself, audit it
+- Empty/missing → audit the most recent pasted article in the conversation;
+ if none exists, ask the user what to audit
@@
-Run the audit on the article identified by `$ARGUMENTS` now.
+Run the audit now using the resolved input rule above (including empty-args fallback).Also applies to: 145-148
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In @.claude/commands/article-audit.md around lines 19 - 24, Update the input
contract text to make `$ARGUMENTS` optional and explicitly document the no-arg
invocation behavior: state that if no arguments are provided the command will
use the user's previous message as the article body (same behavior as the
literal `pasted` case), otherwise treat `$ARGUMENTS` as either a URL (fetch via
`WebFetch`), the literal word `pasted` (use prior message body), or the article
text itself. Ensure the later lines that currently unconditionally instruct "run
using `$ARGUMENTS`" are changed to reflect this optionality and point to the
three cases above (`WebFetch`, `pasted`, or raw article text) so the semantics
are consistent across the document.
Comment on lines
+44
to
+61
| For each claim, search **systematically** through these surfaces in this | ||
| order, and quote the matching rule when found: | ||
|
|
||
| 1. **`/CLAUDE.md`** — canonical hard/soft rules. Use `Grep` for the key | ||
| nouns/verbs (e.g. "compiled queries", "idempotent", "sidecar", "outbox"). | ||
| 2. **`.coderabbit.yaml`** `path_instructions` — file-pattern-scoped guidance. | ||
| 3. **`.claude/agents/architecture-reviewer.md`** "Pattern Checklist" — scan | ||
| rules the agent applies. | ||
| 4. **`.claude/skills/dotnet-performance/`** (project-authored) — deeper why | ||
| behind perf rules. | ||
| 5. **Supporting docs** — read selectively, not exhaustively: | ||
| - `docs/architecture.md` | ||
| - `docs/performance-and-data-correctness.md` | ||
| - `docs/project-decisions.md` (especially for "considered + rejected" | ||
| stances — this is where Dapr/sidecars/etc. live) | ||
| - `docs/cqrs-data-access.md` | ||
| - `docs/dev-loop.md` | ||
|
|
There was a problem hiding this comment.
🛠️ Refactor suggestion | 🟠 Major | ⚡ Quick win
Add docs/STATUS.md to the mapping surfaces.
The audit can recommend opening issues; without checking deferrals/status first, it risks re-proposing intentionally deferred work.
Proposed addition
5. **Supporting docs** — read selectively, not exhaustively:
@@
- `docs/dev-loop.md`
+ - `docs/STATUS.md` (active deferrals / accepted follow-ups)Based on learnings: “Encode discovered patterns/antipatterns in ... STATUS.md (deferrals)”.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In @.claude/commands/article-audit.md around lines 44 - 61, Add docs/STATUS.md
to the audit's mapped surfaces so the audit checks deferrals/status before
recommending work: update the ordered search list (the block that currently
enumerates `/CLAUDE.md`, `.coderabbit.yaml` `path_instructions`,
`.claude/agents/architecture-reviewer.md`, `.claude/skills/dotnet-performance/`,
and the "Supporting docs" list) to include `docs/STATUS.md` (preferably checked
immediately after the "Supporting docs" group or before proposing issues) and
ensure the audit logic that enumerates these surfaces references the new
`docs/STATUS.md` entry so deferrals are discovered before recommending new
tasks.
Comment on lines
+141
to
+147
| ## Example invocations | ||
|
|
||
| - `/article-audit https://www.milanjovanovic.tech/blog/the-idempotent-consumer-pattern-in-net` — fetches + audits | ||
| - `/article-audit pasted` — audits whatever the user pasted in the prior turn | ||
| - `/article-audit` (no args) — audits the most recent pasted article in the | ||
| conversation; if there isn't one, ask what to audit | ||
|
|
There was a problem hiding this comment.
🧹 Nitpick | 🔵 Trivial | ⚡ Quick win
Update slash-command inventory docs for discoverability.
This adds /article-audit, but repo inventory docs shown in context still enumerate only existing commands. Please add this command to the slash-command tables/docs to keep workflow guidance accurate.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In @.claude/commands/article-audit.md around lines 141 - 147, The repository's
slash-command inventory/docs are missing the new /article-audit command; update
the slash-command tables and any command inventory documentation to include
/article-audit with a short description and the three example invocations shown
(full-URL fetch, "pasted", and no-args behavior), and ensure any index or README
that lists available slash commands reflects this addition so discoverability
and workflow guidance remain accurate.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds `.claude/commands/article-audit.md` — a slash command that compares a pasted article (or URL) against this project's existing rule encoding and produces a verdict: covered, divergent, or genuine gap. If the answer is "open an issue," it drafts the issue body inline (ready to paste into `gh issue create`).
Why
Over the last few hours this session, I've done the article-comparison routine three times manually:
The routine is the same each time (extract claims → map to CLAUDE.md / coderabbit / agents / skills / docs → classify → recommend). Encoding it as a slash command makes it reusable + consistent so it doesn't depend on remembering the procedure.
The procedure encoded
Usage
```
/article-audit # fetch + audit
/article-audit pasted # audit content in prior message
/article-audit # audit the most recent pasted article
```
Why a command, not a skill
Per .claude/README.md decision tree:
The procedure is a multi-step audit applied repeatedly, not specialized domain knowledge worth loading on demand. Lives next to `/check-rules`, `/sync-status`, `/new-feature-slice` — same audit-motion category.
Style guardrails baked in
Test plan
🤖 Generated with Claude Code
Summary by CodeRabbit