Menu
Write repository documentation in the house voice: direct, concrete, no AI-tells, only ✅ ❌ emojis
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Reproducible playbook for verifying azure-analyzer is fully clean before/after a release. Covers docs freshness, simulation/mock leakage, runtime correctness, CI green, and PSGallery publish parity. Every step writes its result to the decisions inbox so the run is auditable.
When a multi-track plan references unbuilt modules, decide extract vs consume-as-built
{what this skill teaches agents}
Squad branching model: main-as-trunk workflow with short-lived issue branches
Rubber-duck Copilot PR/issue comments against the 3-model gate before changing any code
| name | docs-voice |
| description | Write repository documentation in the house voice: direct, concrete, no AI-tells, only ✅ ❌ emojis |
| domain | documentation |
| confidence | low |
| source | manual (anonymized from LinkedIn voice profile, first observation) |
All repository documentation (README, CHANGELOG, PERMISSIONS, design docs, PR bodies, decision files, agent histories) must follow this voice profile. Applies to any prose written in committed markdown files visible to readers.
Direct openers. State the position or observation first without warming up. Do not use filler phrases ("In today's world", "As we all know", "I'm excited to share"). Get to the point.
Conclusions before reasoning. Give the answer first, then explain why. Do not build up to a reveal. The reader knows where you stand immediately.
Concrete examples over abstractions. Name specific tools, files, paths, and technologies. Do not talk in abstractions when you can point to something real. "Karpenter subnet sizing" beats "Kubernetes networking".
Pragmatic over theoretical. Seeing reality is more important than making it look nice in diagrams. Value what works in production over what looks good on paper.
Critique with empathy. When challenging an approach, acknowledge why it exists before explaining why it falls short. "Restrictive policy is correct. But without a process for..." not "This is wrong because...".
Accountability over deflection. When something fails, say so plainly. Do not hide behind passive voice. "The wrapper failed to handle..." not "Failures were observed...".
Vary structure. Do not use the same paragraph length or format throughout. Mix one long detailed paragraph, then a short punchy line, then a medium one. The reader should not be able to predict the shape of the next paragraph. Ban 4-paragraph symmetry. No uniform section structure.
These are AI-tells. Never use them:
These survive even when the phrase blacklist is clean:
Lead with the change in one sentence, then the why, then verification steps. No filler opening paragraph.
Example:
Installs the docs-voice profile and audits recent prose for AI-tells.
Applies the directive from copilot-directive-2026-05-12T13-04-28Z
(no AI language, only checkmarks and crosses). Remediates violations in
README, CHANGELOG, PERMISSIONS, decisions.md.
Files changed:
- Skill: .squad/skills/docs-voice/SKILL.md
- Wiring: .copilot/copilot-instructions.md, PR template, agent charters
- Audit fixes: README.md (3 em-dashes), CHANGELOG.md (2 AI-tells), ...
Verification: grep for em-dashes, grep for banned phrases.
Follow Keep a Changelog format. Subject line is imperative present tense without trailing period.
Example:
- docs: install repo-wide docs voice profile and remediate recent prose (#963 follow-up)
Not:
- Documentation: We have installed a new docs voice profile.
Title states the decision verbatim. Body has Context / Options considered / Decision / Consequences sections. No filler introduction.
Example:
## 2026-05-12 — Docs voice profile mandatory
### Context
User directive: all docs must follow the anonymized LinkedIn voice profile.
No AI-tells, only checkmarks and crosses.
### Decision
Install .squad/skills/docs-voice/SKILL.md as canonical reference.
All agents apply it to committed docs.
### Consequences
- Retroactive audit of recent PRs required
- Agent charters link to the skill
- PR template adds docs-voice checklist item
Good:
Wrapper emits tool version + evidence paths. Normalizer maps all Schema 2.2
fields through New-FindingRow.
Bad:
Leveraging the comprehensive wrapper, we're excited to share that the
normalizer now drives enhanced Schema 2.2 field mapping through
New-FindingRow — unlocking robust end-to-end ETL capabilities.
Good:
PSGallery ships only the orchestrator and report renderers. Every external
scanner is a soft dependency and is fetched on demand by the manifest-driven
installer at first run.
Bad:
We're thrilled to announce that PSGallery now offers a cutting-edge
installation experience! Furthermore, all external scanners are
comprehensively managed as soft dependencies. 🎉
Good:
Timeout standardization (#974): Wrapped external CLI invocations in
Invoke-WithTimeout (300s default) across 9 wrappers. Prevents hung CLI
processes from blocking the orchestrator indefinitely.
Bad:
In today's landscape, timeout issues can be a real game-changer when it
comes to CLI reliability. That's why we took a deep dive into
standardization, leveraging Invoke-WithTimeout to unlock robust process
management. At the end of the day, this drives better orchestrator
stability.
What to avoid:
Before finalizing any doc change, check: