sujeet-pro document — draft a technical document (markdown-first)
Turns an intent or a source into a markdown draft engineers actually use. Drafts to a local file. Never publishes. Posting to Confluence / Jira / Slack / GitHub is a separate concern — this skill stops at a clean markdown file and tells you where it is.
The full operating contract lives in this skill folder — read these as you need them:
| Aspect | File |
|---|---|
| How you write (voice, citation rules, anti-patterns) | persona.md |
| The phased process + Workflow orchestration | workflow.md |
| Hard rules + refusals + safety | rules.md |
| Per-artifact contract (lead-with / cap / must-include) | types.md |
Quick start
- Resolve
--typeagainsttypes.md. If the user didn't pass one, infer it from the intent ("write the runbook for…" → runbook) and state the inference in the output. - Gather sources (Phase 0 in
workflow.md). GitHub PR/issue context is theghCLI (gh pr view <url> --json …,gh issue view <url> --json …); repo facts come from Read / Grep / Glob; external links from WebFetch. For a doc that synthesizes multiple systems, fan out thecontext-gathereragent. - Read
persona.mdand adopt the reader-first voice for the chosen--audience(default: engineer). The voice does not mix audiences — pick one. - Draft to
--write-to <path>if given, else a sensible local path (types.mdsuggests one per artifact). Follow the type's lead-with / cap / must-include contract. - Validate (Phase 3): anti-pattern grep, citation check, length cap. Then report the draft path. Nothing is published.
Workflow is the default for multi-source docs
"Always have a workflow." A doc that synthesizes more than one system — an RCA, an ADR weighing alternatives, a migration guide spanning two services — gets the Workflow in workflow.md: fan out context-gatherer + per-section drafting in parallel, stitch, then run a completeness-critic pass that asks "what's missing, what's uncited, what did we assert without evidence?" before the draft survives. A simple, single-source doc (a commit message, a one-screen README section) is drafted inline — say you skipped the Workflow.
Modes
- default — gather, draft, validate, report the local draft path. Nothing is published.
-i— confirm the type, audience, and outline with the user before drafting; walk the draft section-by-section.--deep— use a stronger reasoning profile; auto-select for RCAs, design docs, and anything synthesizing 3+ sources.--write-to <path>— write the draft to a canonical repo path (e.g.docs/adr/0007-x.md) instead of a scratch path. Still a draft; still not published.