Skip to content

lidge-jun/codexclaw / plugins/codexclaw/skills/dev

cxc-dev

Verified

Use for coding, PR delivery, scaffolding and QA. Triggers: develop, fix, refactor, test, review, docs, browse, stacked PR, 개발, 수정, 검토, 스택 PR.

references/reader-documents.md

View on GitHub
# Reader documents — structure for people who were not in the loop

Canonical owner of reader-facing document structure (READER-DOC-01..05). Other
skills point here; they do not restate it. These are agent-followed rules, not
runtime gates.

## When this applies

Anything a person reads to understand or decide: reports, explainers, visual
documents, research reports, PR descriptions, the reader summary at the top of a
devlog `000_plan.md`, and D-phase summaries. It does not apply to audit artifacts
(receipts, ledgers, probe logs, test output, journals): those keep their raw form
and are linked from the document, never rewritten into prose.

The failure this prevents: an agent that ran twelve probes writes a document that
lists the twelve probes. The reader wanted the answer, the reason to believe it,
and what to do next. The probes belong in an appendix.

## READER-DOC-01 Reader contract (DEFAULT)

Before drafting, write one line: **who reads this, what they decide or do after
reading, what they already know.** Then pick one document type and keep to it:

| Type | Reader question | Shape |
|---|---|---|
| Explanation / report | What is true and why? | Answer → why → evidence → next steps |
| Decision record | What did we choose and what does it cost? | Context → drivers → options → decision → consequences |
| How-to | How do I do X? | Goal → prerequisites → numbered steps → verification |
| Reference | What are the exact facts? | Tables and definitions, no narrative |
| Research report | What does the evidence say about Q? | Direct answer → analysis by sub-question → limits → sources |

Mixing types in one document degrades all of them; split instead.

## READER-DOC-02 Answer first (DEFAULT)

Open with the situation, the complication, the question and the answer (SCQA) in
one short paragraph; the governing conclusion appears before any evidence. Korean
documents use 두괄식: 결론·전망·요약을 맨 앞에.

Every heading below it carries what that section establishes, never a bare topic label
("Cost drops 12% under the selected scenario", not "Analysis"). In a decision document
or an explanation that is a claim, and the sections walk the reader from the situation
they accept to the decision being asked (the storyline in
`dev-visualizer/reference/report-writing.md` REPORT-STORY-01). What those documents
avoid is the narrative 기승전결 that withholds the conclusion until the end, not the
progression itself.

**The genre decides whether there is an ask at all.** A research synthesis opens with
its direct answer and then ends at what remains unresolved; a history ends at what is
contested; a reference ends at the definitions, where a topic label is correct rather
than a defect. Forcing any of them to close on a requested decision spends uncertainty
the evidence did not earn (READER-DOC-01 selects the type; the genre table in
`report-writing.md` REPORT-STORY-00 expands it).

## READER-DOC-03 Descending structure (DEFAULT)

Sections descend from the answer: each heading is a summary of what is under it,
siblings do not overlap and together cover the question, and their order follows
the reader's questions rather than the order the work happened. Include a table
of contents once the document exceeds about one screen. Decision documents
also carry three sections writers omit: **non-goals**, **alternatives considered**
with the reason each was rejected, and **consequences or costs** of the choice.
Small changes get a short document; do not inflate a one-paragraph decision.

## READER-DOC-04 Evidence separated and anchored (STRICT for factual claims)

Probes, commands, receipts, screenshots, and logs go to an appendix, an evidence
section or a linked ledger. The narrative cites them by anchor. Every factual
claim in the narrative resolves to one of: an evidence anchor, a source URL with
its date, or a stated assumption. A claim with none of these is removed or labeled
as unverified. Do not paste a command transcript where the reader expects a
conclusion; do not summarize away the evidence either. Both live in the document,
in their own places.

## READER-DOC-05 Fresh-reader check (DEFAULT for C2+; STRICT for user-delivered reports)

An agent or subagent with no task context reads the draft and answers three
questions in its own words: what is the answer, why should I believe it, what do
I do next. Where it stumbled, fix the structure. Record the check (who read,
where they stumbled, what changed) in the evidence section. A reader who has to
read the document twice has found a defect in the document.

For a rendered deliverable (PDF, paged HTML, slides) the fresh reader reads the
rendered pages as images, not the source, so that page breaks, stranded headings,
unreadable figure text and half-empty pages are seen the way the recipient sees
them. Add two questions: which page made you stop, and which visual elements look
like a generated template (cards, tinted boxes, numbered circles, box-and-arrow
figures). Structure fixes come first; layout fixes follow (REPORT-* rules in
`dev-visualizer`).

## Skeletons

Report or explainer:

```markdown
# <Claim-shaped title>
<SCQA paragraph ending with the answer>
## Contents            (when longer than one screen)
## <Claim 1>           supporting reasoning, figure with a caption that states what changes
## <Claim 2>
## What this does not cover / limits
## Next steps          who does what
## Appendix: evidence  A1..An anchors; commands, receipts, screenshots, sources with dates
```

Decision record (MADR-shaped):

```markdown
# <Decision as a sentence>
Status · Date · Deciders
## Context and problem
## Decision drivers
## Options considered   each with pros, cons, why rejected
## Decision
## Consequences         good, bad, follow-ups
```

Visual explainer: question → one figure whose caption states what changes and why
→ detail on demand → sources. Composition and rendering rules stay with
`dev-visualizer`.

Multi-page report (cover, contents, one-page summary, claim headings, numbered
exhibits, appendix, notice): the REPORT-* rules and the paged template in
`dev-visualizer/reference/report-writing.md` and `assets/paged-report.html`.

## Layer order for polish

Structure first (this reference), sentences second. Korean sentence polish is
`kwrite`; general output hygiene is `dev` FAMILY-SLOP-01. Limit a revision to one
or two structural interventions; a document that is rearranged wholesale on every
pass loses the reader's map.

## Sources

Patterns adopted from opened sources with dates and licenses:
`devlog/_plan/260908_narrative_documents/001_sources.md` (Minto Pyramid/SCQA and
MECE, Korean 두괄식 guidance, Amazon narrative memos, Google design docs, MADR,
Diátaxis, Anthropic doc-coauthoring, executive-summary skills). No text is vendored.
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 319kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 319kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 319kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 196kUpdated Claude CodeCodexVerifiedInstall