Optimize documentation for conciseness and clarity by strengthening vague instructions and removing redundancy
Optimize documentation for clarity and conciseness by strengthening vague instructions and removing redundancy. Use when docs need clearer execution criteria or are verbose.
/plugin marketplace add dhruvbaldawa/ccconfigs/plugin install essentials@ccconfigsTask: Optimize {{arg}}
Make docs more concise and clear without vagueness or misinterpretation.
Goals (priority order):
Idempotent: Run multiple times safely - first pass strengthens and removes redundancy, subsequent passes only act if improvements found.
For each instruction section:
Can instruction be executed correctly WITHOUT examples?
Decision: Clear → Step 2 | Vague → Step 3
Check if examples serve operational purpose:
| Keep If | Remove If |
|---|---|
| Defines what "correct" looks like | Explains WHY (educational) |
| Shows exact commands/success criteria | Restates clear instruction |
| Sequential workflow (order matters) | Obvious application of clear rule |
| Resolves ambiguity | Duplicate template |
| Data structures (JSON, schemas) | Verbose walkthrough when numbered steps exist |
| Boundary demos (wrong vs right) | |
| Pattern extraction rules |
DO NOT remove examples yet.
Preserve these even if instructions are clear:
Examples showing EXACT correct vs incorrect when instruction uses abstract terms.
Test: Does example define something ambiguous in instruction?
Numbered workflows where order matters for correctness.
Test: Can steps be executed in different order and still work? If NO → Keep sequence
Comments explaining what output to expect or success criteria.
Test: Does comment specify criteria not in instruction? If YES → Keep
Examples resolving ambiguity when rule uses subjective terms.
Test: Can instruction be misinterpreted without this? If YES → Keep
Annotations generalizing specific examples into reusable decision principles (e.g., "→ Shows that 'delete' means remove lines").
Test: If removed, would Claude lose ability to apply reasoning to NEW examples? If YES → Keep
Before replacing with reference:
If ANY fails → Keep duplicate inline
Before removing ANY content:
Can Claude execute correctly without this?
Does this explain WHY (rationale/educational)?
Does this show WHAT "correct" looks like?
Does this extract general decision rule from example?
❌ Remove (explains WHY):
RATIONALE: Git history rewriting can silently drop commits...
Manual verification is the only reliable way to ensure no data loss.
✅ Keep (defines WHAT "correct" means):
SUCCESS CRITERIA:
- git diff shows ONLY deletions in todo.md
- git diff shows ONLY additions in changelog.md
- Both files in SAME commit
Never sacrifice:
{{arg}}☐ Section: [name] - analyze clarity
☐ Section: [name] - analyze clarity
...
☐ Apply all optimizations
☐ Verify quality standards met
Every change must satisfy:
## Optimization Summary
**Changes Made**:
1. [Section] (Lines X-Y): [Change description]
- Before: [Issue - vagueness/redundancy/verbosity]
- After: [Improvement]
**Metrics**:
- Lines removed: N
- Sections strengthened: M
- Redundancy eliminated: [examples]
**Next Steps**: [Further optimization possible?]