/plain-language

Summary

A sentence a stakeholder can't follow is a decision they can't make. /plain-language rewrites technical content consequence-first — the precise detail stays, repositioned into parentheses where it belongs. No dumbing down, no omissions. Works for anyone who has to decide without knowing the codebase.

When to use

Use /plain-language when the reader is a product owner, stakeholder, or end user who has to make a decision but doesn't know the code or the tech. Two modes:

• Explain mode — you have something to explain (an error, a concept, a technical decision): pass it as an argument and it's rewritten now.
• Convention mode — no topic given: loads the plain-language writing convention for the rest of the session. Other skills (/options, /feature-refinement) invoke this mode automatically.

Trigger phrases (from SKILL.md):

• "explain this simply"
• "what does this error mean"
• "put this in plain language"
• "translate this for a stakeholder"
• "explain the tech so I can decide"

The convention: lead with the consequence, put the mechanism in parentheses. Precise technical detail is never removed — it is repositioned where a non-expert can skip it without losing the point.

Invocation

Pass the content to explain as an argument, or ask a question:

/plain-language [technical content or topic to explain]

With no argument, the skill loads the plain-language convention for the session — subsequent output from skills like /options will follow the convention automatically.

Example 1 — Rewrite a technical sentence

/plain-language "Move dedup into the StabilityGate.advance() barrier so the manifest write stops racing the scan."

Stop the occasional duplicate output when a file is saved twice in quick
succession (move dedup into the StabilityGate.advance() barrier so the
manifest write no longer races the scan).

Example 2 — Explain a concept to a non-technical reader

/plain-language explain what a pre-commit hook does to our CTO

A script that runs automatically before each save to git — it catches
failing tests or banned code before the change lands in the shared repo
(defined in .git/hooks/pre-commit, runs in under 2 seconds on this
project).

Related tools

• /options — Uses /plain-language internally when presenting tradeoffs to stakeholders; invoke it directly to get a structured decision with plain-language framing.
• /feature-refinement — Uses /plain-language to keep the brief readable by non-technical product owners.
• /documentation-standard — Handles doc structure; pair with /plain-language and /doc-voice to get voice and structure right together.