--- name: Happier Documentation slug: happier-documentation category: Writing description: Happier Documentation creates, updates, and reviews internal technical docs and published user/operator/contributor documentation with evidence-backed product truth and release-status accuracy. Use it when changes affect docs or behavior that may make existing documentation incomplete or false. github: "https://github.com/happier-dev/happier/tree/dev/skills/happier-docs" language: TypeScript stars: 1489 forks: 131 install: "npx degit https://github.com/happier-dev/happier/tree/dev/skills/happier-docs ~/.claude/skills/happier-docs" installs_to: ~/.claude/skills/happier-docs source_path: skills/happier-docs/SKILL.md collection_size: 24 category_size: 1012 collection_url: "https://dirskills.com/collections/happier-dev/happier" added: 2026-08-19T07:27:01.697Z last_synced: 2026-08-19T07:27:01.697Z canonical_url: "https://dirskills.com/skills/happier-documentation" --- # Happier Documentation Happier Documentation creates, updates, and reviews internal technical docs and published user/operator/contributor documentation with evidence-backed product truth and release-status accuracy. Use it when changes affect docs or behavior that may make existing documentation incomplete or false. **Install:** ```bash npx degit https://github.com/happier-dev/happier/tree/dev/skills/happier-docs ~/.claude/skills/happier-docs ``` ## README # Happier Documentation Keep documentation truthful, useful, current, and owned without turning every code change into prose churn. Follow the root constitution and, for published docs, `apps/docs/AGENTS.md`. For an explicit deep review or QA request, use `skills/happier-review` as the orchestrator and apply this skill as the documentation-domain standard; this skill does not create a competing general review workflow. ## 1. Classify the documentation impact For the changed behavior or contract, decide whether it affects: - internal technical/product architecture under `docs/**`; - published user/operator/self-hoster/contributor behavior under `apps/docs/content/docs/**`; - both surfaces; - neither surface, with a concrete reason. A refactor that leaves every documented contract unchanged may need no docs edit. A behavior, command, setting, support status, workflow, failure/recovery path, protocol, persistence shape, compatibility rule, deployment requirement, or canonical owner change normally does. ## 2. Identify audience, page type, and canonical owner Classify published pages as task guide, concept, reference, troubleshooting, or development documentation. Internal docs explain architecture, contracts, ownership, and contributor-facing implementation constraints. Search by the feature, command, setting, route, schema, provider/agent id, UI label, error, and reader phrasing before creating a page. Update, move, consolidate, or retire the canonical page instead of adding a parallel explanation. Map links, navigation, related pages, examples, and translations or screenshots that depend on the changed documentation contract. ## 3. Establish product truth and release basis Documentation is a claim, not proof. For Happier behavior: - inspect the reachable implementing producer and consumer, not only a matching string; - identify gates, defaults, platform/provider variation, failure/recovery behavior, and compatibility seams material to the claim; - establish the page's target stable, preview, development, or explicitly future basis from immutable release/artifact evidence when availability is release-sensitive; - distinguish shipped, preview, development-only, experimental, deprecated, planned, and merely possible behavior. README files, existing docs, changelogs, plans, issues, PR descriptions, commit messages, comments, and generated summaries are orientation. They do not independently prove that behavior is reachable or released. For vendor-owned behavior, use current official vendor documentation and keep attribution with the claim. Do not state a competitor's limitation as Happier's own conclusion. Never invent product names, capabilities, support levels, guarantees, dates, quotes, or personal experience. Cut unsupported superlatives and comparisons. Use `skills/happier-compatibility` when documentation claims depend on released/predecessor formats, mixed versions, upgrades, rollback, migrations, or persisted historical data. ## 4. Choose the edit contract Use the narrowest mode that serves the reader: - **Patch:** add or correct bounded material and preserve every unaffected claim, example, link, caveat, and structural choice. - **Polish:** improve clarity and flow while preserving structure, information density, factual scope, and recognizable voice. - **Rewrite:** redesign structure or framing only when explicitly requested or when the current document cannot serve its audience. An approved or preferred version becomes the baseline for later edits. A high change count in a correction pass is a warning sign, not evidence of quality. Every correction is a new claim: verify it as carefully as the text it replaces and do not swap one unsupported absolute for its opposite. Before a substantial rewrite, inventory every material claim involving behavior, commands, settings, support, platforms, providers, compatibility, security, failure/recovery, readiness, and exact names. Account for each in the result. Humanizing is not summarizing. ## 5. Draft for meaning and human voice Write like a thoughtful builder helping another developer: warm, direct, concrete, and technically honest. - Start with the reader's intent or outcome, not the implementation or a promotional hook. - For a substantial unfamiliar system, establish the mental model, normal path, important limits, and why the mechanism matters before cataloguing controls. - Lead with the user consequence, then include enough implementation detail to make the behavior trustworthy. - Keep commands, exact product terms, security boundaries, platform/provider differences, fallbacks, recovery, and readiness close to the claims they qualify. - Use topic headings that remain meaningful without the body and contain words readers recognize. - Avoid promotional fog, artificial urgency, generic importance, invented slogans, repetitive field-label bullets, and definition primarily by negation. - Preserve warmth, useful detail, and natural rhythm. Treat anti-slop patterns as diagnostic signals, not forbidden grammar. - Keep repository paths and implementation trivia out of user/operator prose unless the page is explicitly development-facing. - Never expose secrets, tokens, private URLs, internal-only evidence, or sensitive screenshots. ## 6. Validate the documentation contract Run the narrowest checks that can falsify the edit: - inspect materially changed commands, links, examples, settings, defaults, and support statements; - run `yarn --cwd apps/docs types:check` for published MDX/schema/TypeScript/generated-content changes; - run `yarn --cwd apps/docs build` when routing, navigation, generation, rendering, or production build behavior can be affected; - use current non-sensitive screenshots only when they materially improve a UI-heavy workflow; - for substantial published UI instructions, use the risk-appropriate live product check when runnable and authorized. Do not add wording-policing tests. Validate parsing, generation, routing, links, commands, and factual behavior rather than exact prose. ## 7. Handoff Report: - canonical pages created, updated, moved, consolidated, or intentionally left unchanged; - audience/page type and target release/channel basis; - implementing evidence for decision-material claims; - materially affected surfaces and related pages checked; - validation actually run and anything unavailable; - remaining stale, uncertain, or intentionally deferred documentation and the next action.