lidge-jun/codexclaw / plugins/codexclaw/skills/dev
cxc-dev
VerifiedUse for coding, PR delivery, scaffolding and QA. Triggers: develop, fix, refactor, test, review, docs, browse, stacked PR, 개발, 수정, 검토, 스택 PR.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 12.0 KB |
| agents/openai.yaml | config | 143 B |
| references/async-questions.md | markdown | 6.2 KB |
| references/browser-routing.md | markdown | 3.4 KB |
| references/code-mode-examples.md | markdown | 4.3 KB |
| references/development-practice.md | markdown | 6.3 KB |
| references/hosted-ci-evidence.md | markdown | 3.2 KB |
| references/logging.md | markdown | 2.8 KB |
| references/methodology-overlays.md | markdown | 2.8 KB |
| references/native-execution.md | markdown | 6.3 KB |
| references/peer-collaboration.md | markdown | 10.6 KB |
| references/product/crud-product-development.md | markdown | 2.7 KB |
| references/reader-documents.md | markdown | 6.7 KB |
| references/skill-catalog.md | markdown | 14.1 KB |
| references/skill-ownership.md | markdown | 5.0 KB |
| references/stacked-prs.md | markdown | 16.0 KB |
| references/static-analysis-gate.md | markdown | 2.6 KB |
| references/static-analysis.md | markdown | 3.3 KB |
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.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| 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: 196k | Updated | Claude CodeCodex | Verified | Install |