feat(skills): add /devflow:review-document for prose-doc review#34
Merged
Conversation
New skill: review-document — multi-perspective prose-document review
counterpart to /devflow:write-spike. Reviews KB articles, RFCs, spikes,
runbooks, PRDs, design docs hosted on Google Docs, Confluence, local
files, or arbitrary URLs. Sibling to /devflow:review (which targets
code diffs).
Skill workflow (6 phases):
* Phase 0 — source detection + CLEAN fetch (strips Google Docs
suggestion-mode strikethrough, Confluence change-tracking spans,
Word track-changes) + auto-picks anchor format (file:line for local,
§heading+quote for hosted)
* Phase 1 — linked-ticket pull (Jira via Atlassian MCP) + Hindsight
recall + existing platform comments (Confluence inline/footer with
resolved_state; Google Docs via text/plain export embedding
[a]/[b]/[c] markers — all RAISED-OPEN by default since the export
format does not carry resolved_state)
* Phase 2 — parallel agents dispatched as Task subagents (with
subagent_type per the AGENTS.md role table). Agent set per DOC_TYPE:
KB → critic + writer + document-specialist; spike/RFC → critic +
verifier + architect; runbook → critic + verifier +
security-reviewer; design → critic + writer (+ visual-verdict skill
sequentially)
* Phase 3 — severity scoring + cross-agent dedup + cross-check against
existing comments (NEW / RAISED-OPEN / RAISED-RESOLVED-FIXED /
RAISED-RESOLVED-NOT-FIXED — RAISED-RESOLVED-FIXED moves to Strengths
and is never re-flagged)
* Phase 4 — visual output mirroring /devflow:review (emoji severity,
bold key terms, ≤3 lines per finding, TL;DR)
* Phase 5 — retain learnings to Hindsight
Tessl skill review: 90% (passed create-skill ≥85% gate). Five
optimize-skill iterations all kept at plateau per Tessl-gated Ralph
loop discipline. Subagent spec-review surfaced 0 Critical findings;
4 Important findings applied inline (Task tool/subagent_type dispatch
clarity, visual-verdict-as-skill-not-subagent activation, Google Docs
resolved_state caveat).
Soft dependency on upstream defuddle CLI
(github.com/kepano/defuddle, npm install -g defuddle) for clean web
fetches on arbitrary URLs — falls back to WebFetch when missing.
Defuddle is NOT vendored into devflow; the Formula caveats and
install.sh nudge the user to install it manually.
Files:
* skills/review-document/{SKILL.md, AGENTS.md, TEMPLATES.md}
* devflow-plugin/skills/review-document/{SKILL.md, AGENTS.md, TEMPLATES.md}
(mirror for plugin distribution)
* skills/registry.json — register new skill in code-review category
* Formula/devflow.rb — defuddle soft-dep in caveats
* install.sh — optional defuddle check at end
* README.md — skills table row added (18 → 19 slash commands),
prerequisites note defuddle as optional
* visualizations/architecture/code-review-architecture.md — new
section 5 with full Mermaid flow diagram for /devflow:review-document
* visualizations/architecture/devflow-ecosystem.md — commands table
row added
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
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
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
New devflow skill
/devflow:review-document— multi-perspective review for prose documents (KB articles, RFCs, spikes, runbooks, PRDs, design docs) on Google Docs, Confluence, local files, or arbitrary URLs. Counterpart to the existing/devflow:write-spike(which lives inproof-of-skill). Sibling to/devflow:review(which targets code diffs).resolved_state; Google Docstext/plainexport embeds[a]/[b]/[c]markers — RAISED-OPEN by default), parallelTask-subagent dispatch with per-DOC_TYPEagent sets, severity scoring + cross-agent dedup + cross-check status (NEW / RAISED-OPEN / RAISED-RESOLVED-FIXED / RAISED-RESOLVED-NOT-FIXED), chat-only output mirroring/devflow:review(emoji severity, bold key terms, TL;DR).create-skill≥ 85 % gate. Fiveoptimize-skilliterations all kept at plateau (G1:score(N) ≥ score(N-1)for every iteration; G2:score(final) ≥ score(0)). Subagent spec-review surfaced 0 Critical; 4 Important findings applied inline before opening this MR.npm install -g defuddle) — NOT vendored into devflow per design. Falls back toWebFetchwhen missing.Formula/devflow.rbcaveats +install.shnudge the user.Files
skills/review-document/{SKILL.md, AGENTS.md, TEMPLATES.md}devflow-plugin/skills/review-document/…skills/registry.jsoncode-reviewcategory (layer 3)Formula/devflow.rbcaveatsinstall.shdefuddlecheck at end of installerREADME.mdvisualizations/architecture/code-review-architecture.md/devflow:review-documentvisualizations/architecture/devflow-ecosystem.mdValidated against real-world doc
Tested on a customer-facing WhatsApp Usernames KB draft (Google Doc). Phase 0b clean-fetch via
download_file_content text/plainstripped Google Docs suggestion-mode strikethrough cleanly (rawread_file_contenthad produced ~6 phantom-typo false positives in an earlier manual pass — e.g."version 1Phase 1 limitation"for live text"Phase 1 limitation"). Thetext/plainexport also embeds inline comments as[a]/[b]/[c]markers — discovered during the test, patched into Phase 1c.Test plan
tessl skill review skills/review-document/returns ≥ 90 %/devflow:review-document <google-doc-url>is discoverable and executes Phase 0 → 4 end-to-end🤖 Generated with Claude Code