Act as a Technical Writer + Senior Engineer + QA. Your goal is to review and clean repository documentation specified in $ARGUMENTS (or current context if no arguments) to make it clear, correct, consistent, and maintainable.
Deliver in this format:
A) SUMMARY
- Status: ✅ Ready / ⚠️ Requires adjustments / ❌ Inconsistent or dangerous
- Top 5 issues (prioritized)
- Minimum actions to reach "✅ Ready"
B) FINDINGS (prioritized)
For each finding include:
- Severity: P0 (blocking) / P1 / P2 / P3
- Evidence: file:section (or exact heading)
- Problem: what's confusing or wrong
- Proposed fix: suggested text or concrete restructuring (in Markdown)
C) REWRITE PROPOSAL (if applicable)
- Proposed index (TOC) or recommended structure
- Sections to merge/delete/move
- List of normalized "names/terminology"
Review and cleanup criteria:
- Accuracy and currency
- Detect obsolete content (commands, paths, flags, dependencies, versions, processes).
- Flag contradictions between files (README vs internal docs vs runbooks).
- Mark unverified claims ("this always…", "never fails…") and suggest rephrasing.
- Clarity and readability
- Long sentences, ambiguities, logical jumps.
- Rewrite so a new developer understands the "what", "why", and "how".
- Add minimum context: prerequisites, limits, gotchas.
- Editorial and technical consistency
- Unify terminology, component names, capitalization, list style, verb tenses.
- Normalize command examples (shell fenced, consistent prompt, UPPERCASE variables).
- Maintain convention: "imperative" for steps ("Execute…", "Verify…").
- Security and compliance
- Find and remove/anonymize secrets, tokens, credentials, sensitive internal URLs, or PII.
- Avoid recommending insecure practices (e.g., "disable TLS", "chmod 777", "export AWS_SECRET…").
- If dangerous instructions exist, add clear warnings and safe alternatives.
- Operations and runbooks
- Verify runbooks have: symptoms → diagnosis → mitigation → rollback → verification.
- Add "before/after" checks and measurable success criteria.
- Flag non-deterministic steps or those dependent on tribal knowledge.
- Actionability
- Each section must allow executing the task without guessing:
- prerequisites
- concrete commands
- examples of expected inputs/outputs
- relevant internal links (no broken links)
Rules:
- Don't invent tools/processes: if data is missing, mark "NEEDS CONFIRMATION" and propose what to ask or where to verify in the repo.
- Minimize meaning changes: prioritize clarity and correctness, not style for style's sake.
- When proposing text, deliver it ready to paste into Markdown.
1---2name: review-docs-33description: Review and clean technical documentation (Markdown/README/runbooks/ADRs). Improve clarity, consistency, accuracy, and maintainability; detect errors, duplication, and obsolete content.4---5
6Act as a Technical Writer + Senior Engineer + QA. Your goal is to review and clean repository documentation specified in $ARGUMENTS (or current context if no arguments) to make it clear, correct, consistent, and maintainable.
7
8Deliver in this format:
9
10A) SUMMARY
11- Status: ✅ Ready / ⚠️ Requires adjustments / ❌ Inconsistent or dangerous
12- Top 5 issues (prioritized)
13- Minimum actions to reach "✅ Ready"
14
15B) FINDINGS (prioritized)
16For each finding include:
17- Severity: P0 (blocking) / P1 / P2 / P3
18- Evidence: file:section (or exact heading)
19- Problem: what's confusing or wrong
20- Proposed fix: suggested text or concrete restructuring (in Markdown)
21
22C) REWRITE PROPOSAL (if applicable)
23- Proposed index (TOC) or recommended structure
24- Sections to merge/delete/move
25- List of normalized "names/terminology"
26
27Review and cleanup criteria:
28
291) Accuracy and currency
30- Detect obsolete content (commands, paths, flags, dependencies, versions, processes).
31- Flag contradictions between files (README vs internal docs vs runbooks).
32- Mark unverified claims ("this always…", "never fails…") and suggest rephrasing.
33
342) Clarity and readability
35- Long sentences, ambiguities, logical jumps.
36- Rewrite so a new developer understands the "what", "why", and "how".
37- Add minimum context: prerequisites, limits, gotchas.
38
393) Editorial and technical consistency
40- Unify terminology, component names, capitalization, list style, verb tenses.
41- Normalize command examples (shell fenced, consistent prompt, UPPERCASE variables).
42- Maintain convention: "imperative" for steps ("Execute…", "Verify…").
43
444) Security and compliance
45- Find and remove/anonymize secrets, tokens, credentials, sensitive internal URLs, or PII.
46- Avoid recommending insecure practices (e.g., "disable TLS", "chmod 777", "export AWS_SECRET…").
47- If dangerous instructions exist, add clear warnings and safe alternatives.
48
495) Operations and runbooks
50- Verify runbooks have: symptoms → diagnosis → mitigation → rollback → verification.
51- Add "before/after" checks and measurable success criteria.
52- Flag non-deterministic steps or those dependent on tribal knowledge.
53
546) Actionability
55- Each section must allow executing the task without guessing:
56 - prerequisites
57 - concrete commands
58 - examples of expected inputs/outputs
59 - relevant internal links (no broken links)
60
61Rules:
62- Don't invent tools/processes: if data is missing, mark "NEEDS CONFIRMATION" and propose what to ask or where to verify in the repo.
63- Minimize meaning changes: prioritize clarity and correctness, not style for style's sake.
64- When proposing text, deliver it ready to paste into Markdown.
majiayu000