| name | fs-game-score-docs-diataxis |
| description | Classify, audit, and author files in docs/ against the Diátaxis framework (tutorial / how-to / reference / explanation). Use when adding, restructuring, or reviewing a docs/*.md file — keeps each doc to one quadrant. Excludes design, spec, plan, and archive documents.
|
FS Score Card — docs/ Diátaxis standard
Every prose doc under docs/ belongs to exactly one Diátaxis quadrant. This skill classifies existing docs, flags content that mixes quadrants, and authors new docs in the right place. Files stay flat in docs/ — the quadrant is declared in front matter, not by folder.
Related skills: fs-game-score-flutter-patterns (what the docs describe), fs-game-score-release-engineer (CHANGELOG/release notes — not in scope here).
Scope — what this skill touches
In scope: user- and contributor-facing prose in docs/*.md that explains, teaches, references, or instructs.
Out of scope — never restructure or tag these:
| Excluded | Why |
|---|
docs/*-Design.md design / decision logs | Design / decision log — a record, not Diátaxis prose |
Anything under docs/specs/, docs/plans/, archive/, adr/, rfc/ | Planning artifacts (e.g. docs/specs/2026-05-25-live-score-sharing.md), superseded content |
CHANGELOG.md, AGENTS.md, CLAUDE.md, README.md | Project meta / release records |
| Files whose title or front matter reads "design", "spec", "plan", "proposal", "decision", "RFC", "ADR" | Same reason — record, not documentation |
When asked to "Diátaxis the docs," skip excluded files silently and list them under a "Skipped (out of scope)" heading so the exclusion is visible.
The four quadrants
Classify by two axes: action vs. cognition and acquisition (study) vs. application (work).
| Quadrant | Serves | User is | Answers | Voice |
|---|
| Tutorial | Learning | studying + doing | "teach me by doing" | "we will…", one guaranteed path |
| How-to | A task | working + doing | "how do I accomplish X" | "to do X, do Y", assumes competence |
| Reference | Looking up | working + cognition | "what exactly is X" | dry, factual, scannable tables |
| Explanation | Understanding | studying + cognition | "why is it like this" | discursive, background, trade-offs |
Decision tree
- Is it about doing an activity, or about knowledge?
- Doing → does it serve learning (Tutorial) or a goal the reader already has (How-to)?
- Knowledge → does it describe the machinery (Reference) or illuminate why (Explanation)?
Front-matter tag
Every in-scope doc starts with:
---
diataxis: reference # tutorial | how-to | reference | explanation
---
# Title
If a doc has no front matter yet, add the block above the H1. The tag is the contract the audit checks content against.
Auditing an existing doc
For each in-scope file:
- Classify it with the decision tree; record the intended quadrant.
- Check purity against the anti-mixing rules below. A doc "mixes" when a section does a different quadrant's job.
- Report, don't silently rewrite — list each violation as
file:heading — <quadrant A> content inside a <quadrant B> doc → move/link.
- Only after the user confirms (or when they asked you to author/restructure) do you split or move content.
Anti-mixing rules
- How-to must not teach concepts. Move the "why" to an Explanation and cross-link. (
How-To-Edit-Scores.md is the task steps; Game-Modes.md is the reference it links to.)
- Reference must not explain or instruct. Keep it to facts/tables. (
Semantics-Labels.md and State-Reference.md are clean Reference — use them as the model.)
- Explanation must not be a step list. Prose and trade-offs, not numbered procedures. (
State-Management.md explains; the Riverpod procedure lives in How-To-Riverpod.md.)
- Tutorial must offer one path. No "optionally you could also…"; strip choices that break the guaranteed outcome.
- Reference lives in Reference, even in a how-to. If a how-to needs a table of keys, link to the Reference doc rather than duplicating it.
Authoring or restructuring
- New doc: pick the quadrant first, add the
diataxis: tag, then write in that quadrant's voice. If the request spans two quadrants, create two docs and cross-link — do not blend.
- Splitting a mixed doc: keep the original filename for its dominant quadrant; extract the off-quadrant sections into a new sibling doc; replace the extracted text with a one-line cross-link (
See [Explanation](Foo.md) for why…). Preserve existing inbound links — grep the repo for the old filename/anchors before renaming.
- Cross-links over duplication: quadrants reference each other; they never repeat each other's content.
- Match repo doc style: H1 title, GitHub-flavored Markdown, relative links, tables for reference data (see existing docs).
Current docs/ baseline
Current doc set after the 2026-07-07 restructure. Each doc is one quadrant; verify before acting — content drifts:
| File | Quadrant | Notes |
|---|
Semantics-Labels.md | reference | widget keys / semantics labels |
Help-And-Disclaimers.md | reference | legal / trademark facts |
Game-Modes.md | reference | per-mode scoring rules + internal models |
Game-Modes-Roadmap.md | explanation | future/candidate game modes the app could support |
State-Reference.md | reference | domain model, repositories, prefs keys, key files |
Game-Sync.md | reference | sync providers, wire protocol, handshake |
How-To-Edit-Scores.md | how-to | editing names/scores per mode (extracted from Game-Modes.md) |
How-To-Riverpod.md | how-to | Riverpod coding rules + test setup (extracted from State-Management.md) |
State-Management.md | explanation | state/persistence concepts, provider architecture, startup + splash-race |
Live-Sync-Architecture.md | explanation | sync design intent (extracted from Game-Sync.md) |
Known residual compromises (deliberate, not yet split):
State-Management.md → Provider Architecture keeps two repository-vs-notifier comparison tables inline; they illuminate the distinction (explanation's job) rather than serving cold lookup, so they stay. Field inventory lives in State-Reference.md.State-Management.md → Identified … Problems … Resolved is a record (out-of-scope quadrant); left in place, candidate to move to CHANGELOG.md later.
When restructuring, keep these anchors in their current file — they are linked from AGENTS.md / README / skills / the design doc:
State-Management.md#splash-entry-and-coalesced-persist-race, State-Management.md#live-score-sync-lan-v1, State-Management.md#provider-architecture, How-To-Riverpod.md#integration-and-widget-testing, Game-Sync.md#handshake-and-validation, Game-Sync.md#join-ui-behavior.
Checklist before finishing
