Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
Mirrored from https://github.com/Camo67/composio.git
Synced Nov 21, 07:15 UTC
| 1 | # Audit Process |
| 2 | |
| 3 | ## Procedure |
| 4 | |
| 5 | 1. **Read the `good-docs-writing` skill first** so you audit against its current rules (Voice, Structure, Terminology, Punctuation, Code examples, Formatting). Those rules are the rubric; this skill is the process. |
| 6 | 2. **Read the target file(s) in full** with line numbers. If the user named a directory or glob, enumerate the docs and audit each. If no target is given, ask which file(s) to audit. |
| 7 | 3. **Walk each rule category** against the prose. Note every concrete violation with its line number. |
| 8 | 4. **Write the report** in the format below. Keep suggestions concrete: give the actual rewrite, not "consider revising." |
| 9 | 5. **Stop and present the report.** Offer to apply fixes; apply only if asked. |
| 10 | |
| 11 | ## Prioritized checklist |
| 12 | |
| 13 | Scan for these in roughly this order. The top items most damage the voice: |
| 14 | |
| 15 | 1. **Hedging & filler**: "it might be the case that," "in order to," "basically," "simply," "just." Cut or commit. |
| 16 | 2. **Passive voice** where active is clearer: "the function is invoked by the client" → "the client invokes the function." |
| 17 | 3. **Marketing fluff / vague intensifiers**: "seamlessly," "powerful," "robust," "blazing-fast," "cutting-edge," "world-class." Replace with a concrete claim or delete. |
| 18 | 4. **Em-dashes**: flag every em-dash; the house style bans them. Suggest a period, comma, colon, or parentheses in its place. |
| 19 | 5. **Third-person distance**: "the user," "one," "developers can" where "you" is meant. |
| 20 | 6. **Jargon without context**: an undefined acronym or term-of-art on first use with no grounding. |
| 21 | 7. **Inconsistent terminology**: the same concept named two ways, or core nouns (App, Function, Image, Volume, Secret) miscapitalized or capitalized inconsistently. |
| 22 | 8. **Title-case drift**: heading case that switches between sentence case and title case within one doc. |
| 23 | 9. **Missing backticks**: code identifiers, commands, params, paths, or filenames in plain text. |
| 24 | 10. **Buried warnings**: gotchas, version notes, or gated-feature notes in prose that should be callouts. |
| 25 | 11. **Weak openings**: page or section that doesn't lead with the concept or benefit; throat-clearing before the point. |
| 26 | 12. **Fragment / unrunnable code**: snippets that can't be pasted and run, or missing the expected-output / footgun note. |
| 27 | |
| 28 | ## Report format |
| 29 | |
| 30 | Output a summary line, then findings grouped by severity. Each finding uses this shape: |
| 31 | |
| 32 | ``` |
| 33 | - file.md:42 · [Punctuation] Em-dash banned |
| 34 | Offending: "Modal is fast — really fast — and it scales automatically." |
| 35 | Rewrite: "Modal is fast, really fast, and it scales automatically." |
| 36 | ``` |
| 37 | |
| 38 | Structure the full report as: |
| 39 | |
| 40 | ### Audit: <file or scope> |
| 41 | |
| 42 | **Summary:** <N findings: X high, Y medium, Z low. One-line verdict on overall voice fit.> |
| 43 | |
| 44 | **High** (breaks the voice / reader-facing clarity) |
| 45 | |
| 46 | - `path:line` · [Category] <rule> · Offending: "…" · Rewrite: "…" |
| 47 | |
| 48 | **Medium** (consistency and polish) |
| 49 | |
| 50 | - `path:line` · [Category] <rule> · Offending: "…" · Rewrite: "…" |
| 51 | |
| 52 | **Low** (nits) |
| 53 | |
| 54 | - `path:line` · [Category] <rule> · Offending: "…" · Rewrite: "…" |
| 55 | |
| 56 | **Patterns:** <recurring issues worth a global fix, e.g. "'the user' used 11x, switch to 'you' throughout."> |
| 57 | |
| 58 | ## Rules |
| 59 | |
| 60 | - **Always cite `file:line`** so findings are actionable. Use the line numbers from your Read. |
| 61 | - **Quote the exact offending text**; don't paraphrase the problem away. |
| 62 | - **Give a real rewrite**, in the target voice, for every finding, not generic advice. |
| 63 | - **Map each finding to a style-guide category** (Voice, Structure, Terminology, Punctuation, Code, Formatting) in brackets. |
| 64 | - **Don't invent violations.** If the prose already matches the voice, say so. A short report is a good outcome. |
| 65 | - **Don't edit by default.** Report, then offer to apply. Only write to files when explicitly asked. |