Human Facing Doc Authoring

Human-Facing Doc Authoring

When to load this skill

Load this skill whenever the agent is about to produce or substantially revise a document whose primary audience is a human -- not the agent itself, not a downstream tool. In this ecosystem that includes (non-exhaustive list):

• README.md -- top-level human-facing entry point for any project.
• PLAN.md -- plan-of-record / contract; both humans and agents read.
• notes/survey_.md -- per-paper survey notes; the user reads

these when drafting paper sections and when re-orienting after time away.

• references/_collection_log.md -- bibliography verification audit

trail; the user (and reviewers) read this.

• notes/section_.md -- per-paper-section research notes; the user

reads them while drafting the section.

• notes/impl_.md -- per-component implementation plans;

the user reads them before greenlighting code.

• Reviewer responses / rebuttals.
• Acknowledgement / contribution / changelog files.

Always load this skill before generating any of the above. Other skills (literature-survey, research-paper-writing) cross-reference this one for the structural + stylistic conventions they share.

Do NOT load this skill for:

• editing AGENTS.md files -- those have the opposite audience

(agents). They should be telegraphic and structured, not narrative.

• editing source code or code docstrings -- those have their own

conventions (governed by the project's coding style).

• editing per-skill SKILL.md files -- those are agent-facing.

Core principle: human/agent audience split

Every project in this ecosystem keeps two parallel entry-point documents with explicitly different audiences:

| File | Audience | Tone | |:-------------|:--------------------|:---------------------------------------------| | AGENTS.md | AI coding agents | Telegraphic, structured, machine-parseable. | | README.md | Human collaborators | Narrative, indexed, designed to be SCANNED. |

The same split generalises to every other document the agent produces:

| Document type | Primary audience | Tone | |:------------------------------------|:----------------------|:---------------------------------------| | README.md | New + returning humans | Narrative, two-tier, scannable. | | PLAN.md | Maintainer + co-authors | Structured prose; sectioned; living. | | notes/survey_.md | Paper authors | Compact prose + equations + tables. | | references/_collection_log.md | Maintainer + reviewers | Audit-trail tables; date-stamped. | | notes/section_.md | Paper authors | Working notes; section-flavoured. | | notes/impl_.md | Code authors | Design doc; trade-offs explicit. | | Reviewer-response / rebuttal | Editors + reviewers | Direct; concession-and-concession-counter style. |

Critical: do NOT treat any of these as downstream renderings of AGENTS.md. They have different jobs. AGENTS.md tells an agent what to do; the documents above let a human read what the project IS, what the plan IS, what is known, what is decided.

A well-written human-facing doc should:

• let a new human collaborator decide in 30 seconds whether the

doc (or the project) is relevant to them;

• get a motivated reader the answer they came for in 3-5 minutes;
• contain enough depth that a returning collaborator can **answer

their own question** without paging the maintainer.

Universal conventions (apply to ALL human-facing docs)

These rules apply regardless of doc type. Per-doc-type structure goes in the references/-structures.md files loaded on demand.

A. Orientation up front

• The first paragraph answers "what is this document?" in one

sentence + 2-3 sentences of context.

• Documents longer than ~100 lines have a TOC (Markdown link list)

with anchor-linked entries.

• Documents that primarily exist as audit trails or living records

carry a status / last-updated stamp near the top.

B. Two-tier structure where appropriate

For docs read by both impatient and thorough readers (README.md, PLAN.md, longer survey notes), use a Quick Start / Headline section near the top with the 30-second version, then deeper sections for the 5-minute reader. Cross-reference between the two so the reader can choose their depth.

For shorter docs (a single survey note, a single section note), the two-tier rule reduces to: open with a one-sentence headline, then expand.

C. Heading discipline

• ATX headings only (#, ##, ###). No Setext-style underlines.
• Cap depth at ###. If you need ####, the section needs to be

split.

• One # per document (the title). Top-level sections are ##.
• Pick one capitalisation style (sentence case OR title case) and

apply consistently within a doc.

D. Cross-references

• Every claim that is supported elsewhere should **link to the

supporting location** by anchor (within the doc) or relative path (to another file in the same repo).

• Every "see X" should be a clickable link.
• Use relative links to other files in the same repo

([PLAN.md](PLAN.md)), not absolute URLs.

• For external references that may rot (papers, blog posts), include

the link AND a one-line description so the link's role is obvious even if it 404s.

• Cite code with path/to/file:line_number so the reader can navigate

directly.

E. Tables vs prose vs annotated lists

Prefer tables when:

• there are 3+ items each described by 2-3 attributes;
• the items are parallel (same shape);
• a reader wants to look up a specific item rather than read

top-to-bottom.

Prefer prose when:

• the items are sequential (numbered steps, narrative flow);
• the explanation between items matters as much as the items

themselves;

• there are fewer than 3 items.

Prefer annotated bullet lists (one item per line, with -- or : explaining each) when items are short labels with one-line definitions.

F. ASCII trees for layout

For repository or directory layouts, use a Unicode-box-drawing tree with brief inline annotations:

project-name/
├── AGENTS.md             entry point for AI agents
├── README.md             you are here
└── src/                  source code

Avoid plain ---bulleted lists for layout; the tree shape conveys nesting visually and is far easier to scan.

G. Code blocks

• Tag every code block with a language (bash, python, text, ...).
• Keep bash blocks short -- if a block has more than ~5 commands, it

probably wants surrounding numbered-step prose with shorter blocks inside each step.

• Use `` placeholders for values the reader must substitute.

Comment what to substitute on the line above when not obvious.

H. Math notation

• Use LaTeX inside Markdown via MathJax ($...$ inline,

$$...$$ display) for any equation or symbol.

• Avoid ASCII-art math (e.g. x^2 + y^2); it is harder to scan and

harder to copy.

I. Tone and prose

• Each section opens with one sentence stating what the section is

about.

• Sentences are complete (no telegraphic fragments like "Does four

things").

• Paragraphs are readable (not run-on lists glued together with

commas).

• Prefer active voice; minimise "we" in single-author docs.
• Avoid filler ("In order to ..." -> "To ..."; "It should be noted

that ..." -> delete).

J. Hygiene

• No personal paths (/Users//, author-specific directory

conventions). Use generic placeholders (/...) so the doc is publishable without per-author scrubbing.

• No ` / / ` placeholders that should

have been filled in (vs ones deliberately left for users to substitute).

• Date-stamp every plan-of-record-style doc (`*Created YYYY-MM-DD.

Revised YYYY-MM-DD (note). Maintained by .*`).

K. Self-invalidation of cited facts

Human-facing docs accumulate cited facts -- file counts ("the skill ships 4 references"), line counts ("AGENTS.md is ~680 lines"), enumerations ("the three deferred items are X, Y, Z"), status labels ("F-03..F-08 -- shipped 2026-05-17"), commit SHAs, test counts, citation counts. These facts WILL drift as the underlying state changes; the doc that cites them becomes silently wrong.

The discipline:

1. **Avoid citing facts that will drift, when a cross-reference

suffices.** Instead of "the skill ships 4 references", prefer "see the workflow table in SKILL.md" -- the table is the single source of truth, and the reader who cares about the exact count reads the table.

1. When a drifting fact MUST be cited inline (because the

number itself is load-bearing for the argument: "we covered all 12 rules", "the budget was exceeded by 2.3x"), tag the fact with a self-invalidation marker -- a parenthetical date-stamp + source pointer: ``markdown ... ships 4 references (as of 2026-05-17; see [SKILL.md](SKILL.md) workflow table for current count). `` The marker tells future readers (and future agents auditing the doc) "this number may have drifted; check the source."

1. When updating a doc, audit cited facts. Before committing a

doc edit, scan for inline numbers / counts / enumerations / SHAs in the doc and verify each against its current source. STATUS.md, CHANGELOG.md, README.md "Current status" sections, and per-skill SKILL.md footers are the most-frequent drift sites.

1. Status labels carry their own date. "Shipped" / "planned" /

"deferred" / "blocked" labels must include the date the label was last verified, not just the date the label was added. "F-17 -- planned (as of 2026-05-17)" is correct; "F-17 -- planned" alone will be silently wrong by 2026-06.

This rule was motivated by Session A's STATUS.md / CHANGELOG.md maintenance burden: every commit shifts counts that other docs cite, and without explicit self-invalidation markers the drift accumulates invisibly between sessions.

L. Downstream-doc audit before commit

Subsection K (self-invalidation of cited facts) addresses drift WITHIN a single doc. This subsection L addresses the complementary failure mode: drift ACROSS docs. When a non-trivial change lands (a new skill ships, a new template ships, a count changes, a section gets renamed, a convention changes), DOWNSTREAM docs that reference the changed thing become silently stale unless the agent audits them explicitly. K + L together: K helps the next reader recognise stale content; L prevents the content from becoming stale in the first place.

The discipline: before committing any non-trivial change, run the following 3-step audit.

Step 1: identify the change-class

Classify the change as either trivial or non-trivial:

• Trivial (no audit required): typo fixes, internal

reformatting, ASCII↔Unicode conversions, code-comment edits, whitespace cleanups, single-word phrasings, fixing broken links.

• Non-trivial (audit required): new skill / template / file;

removed skill / template / file; renamed section or file; changed count (how many skills ship, how many references in a skill, how many entries in some list); changed convention or default; changed status label (planned -> shipped, deferred -> active); new external dependency; new GitHub-issue template category; project's first real-project bootstrap.

If you cannot quickly classify a change as trivial, treat it as non-trivial.

Step 2: enumerate the standard downstream docs to audit

For ANY non-trivial change to this repo, the standard audit list is:

| Doc | Drift-prone content | |:-------------------------------------------------|:---------------------------------------------------------------------------------------------------------------------| | README.md | "What you get" inventory; status callout; repo-layout tree; "Feedback from real projects" categories; section dates. | | STATUS.md | Well-grounded / informed-prediction classification; evidence-count table; roadmap-condition progress. | | CHANGELOG.md | Per-session section; cross-references to commits. | | AGENTS.md | Section 5 skills index table; templates index table; Section 6 universal conventions when convention changes. | | Per-skill SKILL.md footers | "References shipped / planned" counts; date-stamp; cross-references between skills. | | Per-template README.md | "What this template ships" inventory; placeholder lists. | | .github/ISSUE_TEMPLATE/*.md | "The four shipped skills are ..." or similar count-bearing prose. | | notes/agent_feedback.md (per project) | Cross-references to upstream commits / issues from prior entries. |

For ANY non-trivial change to a per-project repo using this framework, the standard audit list reduces to:

| Doc | Drift-prone content | |:---------------------------------------------|:---------------------------------------------------------------------------------------------| | README.md | Status / current-version statements; "what this project is" headline; feature inventory. | | PLAN.md | Status section; milestone progress; "current phase" markers. | | AGENTS.md Project facts | Status, current phase, code dependencies (especially pinned versions). | | notes/README.md | Indexes of survey / impl / section notes. | | notes/_resolved/INDEX.md (if changed) | Entries table. | | notes/_archive/INDEX.md (if changed) | Entries table. |

Step 3: open + audit each, then update or annotate

For each doc on the relevant list:

1. **Open the doc + scan for content that cites the changed

thing.** Cross-references, counts, enumerations, status labels, inventories. Use Grep when faster than Read.

1. If a cited fact is now stale, update it (or apply the

K-rule self-invalidation marker if the update would be disproportionate to the value).

1. If the doc is clean, note it explicitly ("README.md

audited; nothing to update") so the user has a record that the audit happened.

The audit should be visible in the response to the user, NOT silent. Frame it as a checklist:

Downstream-doc audit (per F-20):
- README.md: status callout + What-you-get table updated [DONE]
- STATUS.md: evidence-count table + retirement-condition #4 updated [DONE]
- CHANGELOG.md: new section appended [DONE]
- AGENTS.md skills index: no change needed (this change doesn't add/remove a skill)
- per-skill SKILL.md footers: no change needed
- .github/ISSUE_TEMPLATE/: no change needed (no count change)

Why this matters

Without an explicit audit step, the agent treats each doc as independent and only updates the on

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: a-attia
• Source: a-attia/scicomp-research-skills
• License: MIT

Install and usage instructions live in the source repository linked above.