feat: migrate skills review desk to astro

2026-09-05 16:54:37 +00:00
parent 107e429fb9
commit 71e4775573
66 changed files with 8184 additions and 96 deletions
@@ -0,0 +1,100 @@
+---
+name: unslop
+description: Strip AI phrasing from prose before it is posted to a Confluence page, sent to a customer, or shared in chat. Use when a draft sounds like it was written by an LLM: ornamental hedging, breathless transitions, vague intensifiers, symmetrical bullet padding, or any of the other tells listed in references/tells.md.
+---
+
+# Unslop
+
+The page-reviewer catches structural problems; this skill catches voice
+problems. Both run before a page goes live.
+
+The unslop pass is line-anchored, deterministic, and reversible. It returns a
+diff-style report; the author or the calling skill applies the changes.
+
+## Hard rules
+
+- **Never edit silently.** Every change appears in the report with the line,
+  the original phrase, and the suggested replacement.
+- **Never invent voice.** The rewrite defaults to short, declarative, and
+  Netcracker-house — see [references/house-style.md](references/house-style.md).
+- **Don't rewrite technical content.** If a sentence is slop but the
+  technical claim is correct, fix the phrasing, not the claim.
+- **Don't rewrite quotes.** Code, command output, error messages, and
+  customer-quoted text stay literal.
+- **Don't touch structured data.** Tables, lists of identifiers, file paths,
+  URLs, and version numbers are not slop.
+
+## Workflow
+
+1. Read the draft. Mark each line with one of: `clean`, `slop`, `unsure`.
+2. For each `slop` line, look up the tell in
+   [references/tells.md](references/tells.md) and propose a concrete rewrite.
+3. For each `unsure` line, leave it alone and flag it for the author with a
+   short rationale.
+4. Cluster check. If more than 5 slop lines appear in a 30-line block, mark
+   the block `rewrite-block` — voice problems cluster, and the author should
+   rewrite that section by hand rather than accept a chain of small fixes.
+5. Return the report.
+
+## Report shape
+
+```
+# Unslop report — <page slug>
+
+L<line>: <tell> — <phrase>
+  > <original>
+  + <proposed rewrite>
+L<line>: <tell> — <phrase>
+  > <original>
+  + <proposed rewrite>
+
+# Rewrite-block sections (cluster of >5 slop lines)
+- L<start>-L<end>: <section title>
+
+# Uncertain — author decides
+- L<line>: <short rationale>
+```
+
+The calling skill applies line-by-line fixes; the author rewrites the marked
+sections.
+
+## What counts as slop
+
+Full list with examples in [references/tells.md](references/tells.md). The
+high-frequency ones:
+
+| Tell | Example | Fix |
+|------|---------|-----|
+| Ornamental hedging | "It's important to note that…" | Delete the preamble. |
+| Breathless transition | "Let's dive in!" | Replace with the next fact. |
+| Vague intensifier | "really", "very", "quite" (when not load-bearing) | Delete. |
+| Symmetric padding | "X is Y. X is also Z. Both X's are…" | Pick the one that matters. |
+| AI résumé | "With over X years of experience…" | Replace with the actual fact. |
+| Performative caveat | "It's worth mentioning that…" | Delete or move to the conclusion. |
+| Marketing tone | "seamlessly", "robust", "powerful", "leverage" | Replace with the specific capability. |
+| Triplet | "fast, reliable, and scalable" | Pick the one that is actually true, drop the rest. |
+| Heading question | "Why is X important?" | State the answer, not the question. |
+| Sign-off | "Hope this helps!", "Let me know if you have questions!" | Delete. |
+
+## When to refuse
+
+- The text is a customer-quoted block, a log line, or a code comment — leave
+  it alone.
+- The text is technical and correct; only the framing is fluffy. Fix the
+  framing, not the substance.
+- The rewrite would change the meaning. Mark it `unsure` and let the author
+  decide.
+
+## Related
+
+| Skill | Role |
+|-------|------|
+| `page-reviewer` | Calls unslop as part of the pre-post gate |
+| `confluence-page` | Uses the report to apply line-by-line fixes |
+
+## Limitations
+
+Unslop is a heuristic pass, not a guarantee. A page can be technically
+slop-free and still sound corporate, and a page that sounds conversational
+can still be slop-free. Voice is not the only quality dimension; this skill
+addresses one of them.