From majestic-tools
Reviews brainstorms, plans, PRDs for clarity, completeness, specificity, YAGNI violations, vagueness, and gaps before workflow handoff. Scores criteria and flags blocking issues.
npx claudepluginhub majesticlabs-dev/majestic-marketplace --plugin majestic-toolsThis skill uses the workspace's default tool permissions.
Structured review to answer: "Is this document clear and ready for the next phase?"
Refines brainstorm and plan documents by assessing clarity, completeness, specificity, YAGNI, and scope issues, then auto-fixes minor problems or proposes substantive changes before next workflow steps.
Reviews and refines brainstorm or planning documents before implementation. Identifies gaps, clarifies assumptions, scores against clarity-completeness-specificity criteria, and applies targeted updates.
Critiques research, plan, brainstorm, and QA documents for completeness, gaps, weaknesses, and quality issues using structured process with user preferences.
Share bugs, ideas, or general feedback.
Structured review to answer: "Is this document clear and ready for the next phase?"
Audience: Engineers reviewing brainstorm outputs, plans, or PRDs before handoff. Goal: Catch vagueness and gaps early. Auto-fix minor issues, flag substantive ones.
Score each 1-5:
| Criterion | 1 (Fail) | 3 (Acceptable) | 5 (Excellent) |
|---|---|---|---|
| Clarity | Vague language, undefined terms | Mostly clear, few ambiguities | Every statement is actionable and specific |
| Completeness | Missing required sections | Has all sections, some thin | All sections substantive with no gaps |
| Specificity | "Handle errors appropriately" | Some concrete details | Exact behaviors, values, and boundaries defined |
| YAGNI | Speculative features, gold-plating | Minor scope creep | Every item traces to a stated requirement |
| User Intent Fidelity | Drifted from original request | Mostly aligned | Precisely captures what user asked for |
DOCUMENT = read target document
DOC_TYPE = classify(DOCUMENT) → brainstorm | plan | prd | other
REQUIREMENTS = load references/document-type-requirements.md[DOC_TYPE]
VAGUE_PATTERNS = load references/vague-language-patterns.md
Step 1: Structural Check
For each REQUIRED_SECTION in REQUIREMENTS[DOC_TYPE].sections:
If REQUIRED_SECTION missing from DOCUMENT:
findings.blocking.append({type: "missing_section", section: REQUIRED_SECTION})
Step 2: Vagueness Scan
For each LINE in DOCUMENT:
If LINE matches VAGUE_PATTERNS.qualifier_words OR VAGUE_PATTERNS.hedge_phrases:
If context is risk-identification OR explicit-deferral:
skip (acceptable vagueness)
Else if fix is obvious (simple word replacement):
auto_fixes.append({line: LINE, fix: replacement})
Else:
findings.blocking.append({type: "vague_language", line: LINE, suggestion: "specify X"})
Step 3: Criteria Scoring
For each CRITERION in [Clarity, Completeness, Specificity, YAGNI, User Intent Fidelity]:
score[CRITERION] = assess(DOCUMENT, CRITERION) → 1-5
If score[CRITERION] < 3:
findings.blocking.append({type: "low_score", criterion: CRITERION, details: "..."})
Step 4: Categorize Findings
blocking = findings where score < 3 OR missing required sections
polish = findings where score 3-4 (improvable but not blocking)
## Document Refinement Report
**Document:** [filename or title]
**Type:** [brainstorm | plan | prd]
**Verdict:** READY | NEEDS REVISION
### Scores
| Criterion | Score | Notes |
|-----------|-------|-------|
| Clarity | X/5 | ... |
| Completeness | X/5 | ... |
| Specificity | X/5 | ... |
| YAGNI | X/5 | ... |
| User Intent Fidelity | X/5 | ... |
### Auto-Fixed (applied)
- [Line X]: "should handle" → "returns 422 with error message"
### Blocking Issues
1. [Issue]: [What's wrong] → [What to specify]
### Polish Suggestions
- [Improvement that would raise score but isn't blocking]
MAX_ROUNDS = 2
If VERDICT == "NEEDS REVISION":
Apply auto-fixes directly to document
Present blocking issues to user
User addresses blocking issues
Re-run assessment (round 2)
If round 2 still has blocking issues:
Present remaining issues
Ask user: "Ship as-is or address remaining items?"
Do NOT run round 3 (diminishing returns)
| Anti-Pattern | Why It's Wrong | Instead |
|---|---|---|
| Reviewing implementation code | This skill is for documents, not code | Use code-review or plan-review |
| Scoring every line | Over-analysis kills velocity | Focus on section-level assessment |
| Blocking on style preferences | "I'd phrase it differently" isn't a gap | Only block on missing information or ambiguity |
| Expanding scope during review | "You should also add X" | Only flag what's missing per doc-type requirements |
| Perfect scores required | 3/5 on all criteria = ready to proceed | Block only on scores below 3 |