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.