managing-design-documents

Author, publish, and validate registered design-document sources with policy-driven PDF generation.

Updated Jul 9, 2026
One-click install
npx skills add https://github.com/alsdmlals4-eng/Base --skill managing-design-documents-alsdmlals4-eng
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: managing-design-documents
Source: https://github.com/alsdmlals4-eng/Base/tree/main/skills/managing-design-documents
Command: npx skills add https://github.com/alsdmlals4-eng/Base --skill managing-design-documents-alsdmlals4-eng

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Game and creative projects accumulate design decisions across chats, Notion pages, Google Sheets, and scattered documents, causing duplicated sources of truth, stale PDFs, and lost approvals. This Skill enforces a single canonical ownership model where every design question has exactly one registered repository source, approved decisions are written immediately, and human-readable PDF views are regenerated by policy. ## Core Features & Use Cases - Canonical source lifecycle: Author, update, restructure, publish, and validate registered Markdown/JSON design documents through five explicit modes without re-judging the same facts. - Decision synchronization: Record approved decisions in GitHub tracking surfaces and CURRENT_CONFIRMED_DECISIONS.md immediately, then propagate to affected domain sources with commit SHA traceability. - Policy-driven publication: Generate PDFs, optional DOCX, and diagrams only when the registry policy (source_only, milestone_sync, always_sync) requires it, with full-page render validation and atomic output replacement. - Use Case: After a user approves a new combat system rule, the Skill records the decision with its ID, updates the canonical Markdown source and confirmed-decisions ledger, merges via PR, regenerates the milestone PDF at the exact source SHA, and verifies no drift between repository, PDF, and any legacy Notion exception. ## Quick Start Use the managing-design-documents skill to update the combat system design document with the newly approved rule and republish its milestone PDF.

Frequently Asked Questions about managing-design-documents

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I manage game design documents without duplicate sources of truth?

Register each document in a design document registry that declares one canonical Markdown or JSON source per question. Derived views like PDFs and Notion pages must reference that source rather than reimplementing its content independently.

How to keep approved design decisions synchronized with documentation?

Record each approval immediately in the GitHub tracking surface and CURRENT_CONFIRMED_DECISIONS.md, then update the affected domain source in the same workflow. Verify decision IDs, commit SHAs, and derived PDF source SHAs match before reporting SYNCED status.

When should design documents be published as PDF?

Publication follows the registry policy: source_only documents never generate PDFs, milestone_sync documents regenerate at major gates, and always_sync documents regenerate whenever sources change. PDFs are validated with full-page rendering before atomic replacement.

Can I still use Notion or Google Sheets for game design documentation?

Notion is read-only legacy migration source or an explicit V4 exception with recorded approval, scope, and exit conditions. Google Sheets is compatibility-only for migrating existing unique material into repository canonical sources, never a new default workspace.

What is the difference between a feature design spec and a traceability packet?

The L2 feature design spec owns intended player-facing behavior, rules, states, and acceptance criteria after PoC survival. The traceability packet is a non-canonical derivative linking approved requirements to tasks, implementation, and verification evidence without duplicating spec content.

Why does design document validation fail after a PDF is generated?

Validation fails when the PDF source SHA does not match the current repository SHA, full-page rendering was not performed, or the manifest hashes are stale. CURRENT status, human visual review, and runtime verification are independent states that must each pass separately.