# Codex Document Writer

> Use for documents, reports, memos, guides, academic papers, or formal text that needs clear structure, reliable tone, formatting, and diagrams.

- Skill: `bang-isme/codex-document-writer` (Agent Skill, multi-file: 10 files)
- Install (CLI): `npx skillmds@latest add bang-isme/codex-document-writer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/bang-isme/codex-document-writer/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: Bang-isme (https://skillmd.com/u/bang-isme)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/bang-isme/codex-document-writer

---


## TL;DR
Load before writing or revising any document, report, proposal, memo, guide, academic paper, or long-form explanation. The goal is reader clarity: correct context, full meaning, professional structure, reliable tone, compact wording, proper diagrams, and polished formatting — without making the reader infer missing intent.

## Activation

1. Activate when the task involves drafting, rewriting, summarizing, formatting, or improving documents, reports, memos, proposals, guides, handoffs, emails, academic papers, or formal text.
2. Activate on `$doc`, `$report`, `$write`, `$diagram`, `$báo-cáo`, "soạn tài liệu", "viết báo cáo", "làm văn bản chuyên nghiệp", "viết rõ ràng hơn", "vẽ sơ đồ".
3. Auto-load with `codex-reasoning-rigor` when the document is decision-heavy, high-stakes, or evidence-based.
4. Auto-load with `codex-doc-renderer` when the deliverable is `.docx`.

## Hard Rules

- Always identify purpose, audience, context, and expected use before choosing wording.
- Start with the document outcome, not background narration.
- Use complete sentences with explicit actor, action, object, and outcome.
- Keep each paragraph focused on one message; do not make the reader infer the point.
- Be detailed where meaning depends on detail, but remove filler, repeated framing, and synonym stacking.
- Use humble, reliable wording: state what is verified, what is inferred, and what remains uncertain.
- Do not overclaim. Avoid "clearly", "obviously", "guaranteed", "always", and "never" unless evidence supports them.
- For Vietnamese, use natural UTF-8 Vietnamese, correct context labels, and professional but readable wording.
- Every diagram must answer a specific question. No decorative diagrams.
- Every report section must earn its place. No empty sections or placeholder text.

## Document Flow

Before drafting:

1. Determine document type and reader.
2. Pick the matching structure:
   - For reports → `references/report-structures.md`
   - For general documents → `references/document-types.md`
   - For academic/university work → `references/academic-report-patterns.md`
3. Add diagrams where visual explanation is needed → `references/diagram-patterns.md`
4. Apply content writing patterns → `references/content-writing-patterns.md`
5. Apply sentence rules from `references/sentence-quality.md`.
6. Apply reliability rules from `references/tone-reliability.md`.
7. Apply Vietnamese wording rules from `references/vietnamese-style.md` when writing Vietnamese.
8. Apply formatting rules from `references/formatting.md`.

## Diagram Integration Protocol

When the document needs visual explanation:

1. Check `references/diagram-patterns.md` → Diagram Selection Decision Table
2. Choose the simplest diagram type that answers the reader's question
3. Use Mermaid syntax for rendered documents, ASCII for plain text
4. Add a caption/title before every diagram
5. Limit: max 15 nodes per diagram, split if larger
6. Verify render before delivering

### Quick Diagram Dispatch

| Need | Diagram Type | Mermaid Keyword |
|---|---|---|
| System architecture | Flowchart with subgraphs | `flowchart TB` |
| API interaction flow | Sequence diagram | `sequenceDiagram` |
| Database schema | ER diagram | `erDiagram` |
| Status/workflow transitions | State diagram | `stateDiagram-v2` |
| Project timeline | Gantt chart | `gantt` |
| Branch strategy | Git graph | `gitGraph` |
| Feature breakdown | Mind map | `mindmap` |
| Distribution/proportion | Pie chart | `pie` |
| Milestone overview | Timeline | `timeline` |

## Report Type Router

| Signal in User Request | Load Reference |
|---|---|
| "báo cáo tiến độ", "progress report" | `references/report-structures.md` → Progress Report |
| "phân tích", "analysis", "analytical" | `references/report-structures.md` → Analytical Report |
| "đề xuất", "proposal" | `references/report-structures.md` → Proposal |
| "sprint report", "release notes" | `references/report-structures.md` → Sprint Report |
| "incident", "postmortem", "sự cố" | `references/report-structures.md` → Incident Report |
| "đồ án", "assignment", "bài tập lớn", "luận văn" | `references/academic-report-patterns.md` |
| "memo", "update", "thông báo" | `references/document-types.md` → Business Memo |
| "hướng dẫn", "guide", "tutorial" | `references/document-types.md` → User Guide |
| "handoff", "bàn giao" | `references/document-types.md` → Session Handoff |
| "README", "documentation" | `references/content-writing-patterns.md` → README Template |

## Quality Gate (Before Delivery)

Before delivering any document:

- [ ] First section answers the reader's primary question
- [ ] Every claim backed by evidence
- [ ] Tables used for comparisons, not narratives
- [ ] Every diagram has a caption and answers a specific question
- [ ] Metrics shown with target vs actual
- [ ] Clear "Next Steps" or "Required Decision" section
- [ ] Risks listed with severity AND mitigation
- [ ] For Vietnamese: proper section headings and figure/table numbering
- [ ] Scannable: headings + tables alone convey the gist
- [ ] No wall-of-text paragraphs (max 5-6 lines per paragraph)
- [ ] No "empty calories" phrases ("it is important to note that...", "in order to...")

## Reference Files

- `references/document-types.md`: templates for reports, memos, proposals, guides, handoffs, summaries, and executive updates.
- `references/report-structures.md`: 8 report types — progress, analytical, proposal, comparison, sprint, incident, research, and Vietnamese academic.
- `references/diagram-patterns.md`: complete Mermaid diagram reference — flowchart, sequence, ER, state, Gantt, C4, journey, mindmap, pie, gitGraph, timeline + ASCII alternatives + quality rules.
- `references/content-writing-patterns.md`: PREP framework, heading hierarchy, active voice, "So What?" test, Vietnamese content patterns, anti-patterns, and README template.
- `references/academic-report-patterns.md`: Vietnamese university report template — 6 chapters, cover page, TOC, figure/table lists, formatting standards, citation guide, and common academic phrases.
- `references/sentence-quality.md`: sentence patterns that keep meaning complete, compact, and easy to read.
- `references/tone-reliability.md`: humility, evidence wording, uncertainty, and confidence calibration.
- `references/vietnamese-style.md`: Vietnamese document labels, wording patterns, and anti-filler rules.
- `references/formatting.md`: professional headings, tables, bullets, spacing, and scan-friendly layout rules.