AI Skill Report Card
Compiling Technical KB Documentation
Quick Start15 / 15
Given raw input like:
Audience: IT Staff
Article Type: Troubleshooting
Telemetry: Users on VPN client v4.2 report disconnects every 15 min on Windows 11.
Error in logs: "Tunnel renegotiation failed - code 0x80090326"
Output directly (no preamble):
Markdown# VPN Disconnects Every 15 Minutes on Windows 11
Recommendation▾
Add an example for the End User audience to fully demonstrate the calibration table in action
Symptoms
- Users report VPN connection drops approximately every 15 minutes.
- Event logs show error:
Tunnel renegotiation failed - code 0x80090326.
Affected Environments
- VPN Client v4.2 on Windows 11.
Prerequisites
- Administrative access to client machine or endpoint management console.
- VPN client logs enabled at debug level.
Resolution Steps
- Open the VPN client diagnostic log viewer.
- Confirm the renegotiation interval setting under Advanced Settings.
- Set the renegotiation timeout to 60 minutes. You will see the "Session TTL" field update to 3600s.
- Restart the VPN client service.
Still Having Issues?
Escalate to Tier 2 with the client log file, Windows build number, and timestamp of last disconnect.
Workflow14 / 15
Progress:
- Parse input telemetry for: audience, article type, raw technical facts
- Identify mandatory fields per skeleton (symptoms, environments, prerequisites, etc.)
- Flag any missing-but-required data with
<!-- VERIFY: ... -->instead of inventing it - Select exactly one skeleton (Troubleshooting / How-To / Known Issue) — never blend
- Write content calibrated to the audience's vocabulary and granularity level
- Mask any literal secrets, hostnames, customer names, connection strings
- Final pass: strip all conversational filler, verify output starts with
#title
Recommendation▾
Include a brief example of masking secrets/hostnames in practice (before/after) since it's emphasized twice in Best Practices
Audience Calibration Reference
| Audience | Vocabulary | Granularity |
|---|---|---|
| End User | Plain language, define all acronyms | Click-by-click, exact UI paths, visual anchors |
| IT Staff | AD, DHCP, MDM, provisioning | Diagnostic triage, error codes, escalation thresholds |
| Developer | REST, env vars, schemas, stack traces | Config syntax, code blocks, log paths |
| SysAdmin | Kernel, daemons, cron, elevated execution | Full shell commands, permissions, service restarts |
Skeleton Selection
- Troubleshooting: User has an active, reproducible problem needing a fix → Symptoms, Affected Environments, Prerequisites, Resolution Steps, Escalation
- How-To Guide: User wants to accomplish a goal, no problem exists yet → Goal, Prerequisites, Steps, Verification, Related Tasks
- Known Issue: Confirmed defect with no permanent fix yet → Symptoms, Affected Environments, Root Cause, Workaround, Status
Never mix sections across these three types.
Examples17 / 20
Example 1 — Developer / How-To
Input: "Devs need to enable debug logging for the payments-api service via env var."
Output:
Markdown# How to Enable Debug Logging for payments-api
Recommendation▾
Consider showing a 'bad output' example (e.g., fabricated version number) alongside the good one to reinforce the anti-hallucination rule
Goal
Enable verbose debug-level logging output for the payments-api service in local and staging environments.
Prerequisites
- Access to the service's
.envfile or deployment config. - Ability to restart the service process.
Step-by-Step Instructions
- Set
LOG_LEVEL=debugin the service's environment configuration. - Restart the payments-api process.
a. Run
systemctl restart payments-api(if managed via systemd). b. Confirm restart withsystemctl status payments-api.
Verification
You will know it worked when log output at <!-- VERIFY: exact log file path --> includes [DEBUG]-prefixed entries.
Related Tasks
- Configuring log rotation for payments-api
- Shipping logs to centralized logging service
**Example 2 — Missing data handling**
Input: "Known issue: app crashes on launch for some users, no root cause identified yet."
Output includes:
```markdown
Root Cause
Under active product team investigation.
Current Status
No permanent code-fix or patch is currently deployed. Active tracking status: <!-- VERIFY: Insert internal or external tracking ticket indicator -->.
Best Practices
- Start output immediately with the
#title — zero preamble, zero sign-off. - One skeleton per request. If article type is ambiguous, default to Troubleshooting.
- Every resolution/instruction step: single action, active voice, under 30 words.
- End resolution/verification steps with an observable confirmation cue where possible.
- Treat any version number, hostname, file path, or ticket ID not explicitly given as unverifiable — flag it, don't fabricate it.
- Mask real secrets/hostnames/customer names with semantic placeholders like
<YOUR_DATABASE_HOST>even if present in input telemetry.
Common Pitfalls
- Do not write "Here is the documentation:" or any conversational wrapper.
- Do not invent plausible-sounding ticket numbers, version strings, or file paths to fill gaps — always use the
<!-- VERIFY: ... -->flag instead. - Do not blend skeleton sections (e.g., adding "Root Cause" to a How-To Guide).
- Do not use jargon in End User content, even common acronyms, without defining them inline.
- Do not leave real customer/internal data unmasked, even when quoted directly from the source telemetry.