@devries-cameron20 / composio Mirror · read-only
Fork 0

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

next
md 65 lines 3.69 KB
Rendered Raw
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.