design-doc

Expand design doc templates and review drafts for guideline compliance.

Updated Nov 4, 2022
One-click install
npx skills add https://github.com/CityBear3/dotfiles --skill design-doc-citybear3
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: design-doc
Source: https://github.com/CityBear3/dotfiles/tree/main/claude/skills/design-doc
Command: npx skills add https://github.com/CityBear3/dotfiles --skill design-doc-citybear3

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

This Skill helps you produce high-quality formal Design Docs that capture rationale, trade-offs, and architectural intent without turning the document into ghostwritten implementation notes.

Core Features & Use Cases

  • Template expansion for consistent structure: creates a Design Doc skeleton with the expected sections and metadata placeholders.
  • Editor and sounding-board workflow: supports you by researching context, prompting for clarifications, and reviewing your draft for guideline adherence.
  • Quality checks while you write: detects ambiguity, redundancy across sections, and missing or inconsistent guideline coverage.
  • Clear “when to use” guidance: helps decide whether a design doc is warranted versus skipping straight to planning for smaller changes.

Use case example: You’re planning a cross-cutting architectural change affecting multiple components, and you need a Design Doc that future engineers can use to understand intent, constraints, and decision trade-offs.

Quick Start

Use the design-doc skill to produce a Design Doc outline for the topic "Async event routing for order processing".

Frequently Asked Questions about design-doc

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

FAQPage Schema
How do I write a design doc that captures architectural rationale and trade-offs?

Use the design-doc skill to produce formal Design Docs that capture rationale, trade-offs, and architectural intent. It expands a template skeleton and enforces an editor workflow where you author the prose while it prompts for clarifications and checks guideline compliance.

When should I create a design doc versus skipping straight to planning?

You need a design doc for cross-cutting architectural changes affecting multiple components where future engineers need to understand intent and constraints. For smaller changes, you can skip straight to planning without formal documentation.

How do I prevent ghostwritten prose in technical documentation?

The design-doc skill enforces a strict editor workflow where you author the prose while the skill expands templates, prompts for ambiguities, and reviews drafts for redundancy and guideline adherence, preventing ghostwritten implementation notes.

How do I check a design doc for ambiguity and missing guideline coverage?

The skill performs quality checks while you write by detecting ambiguity, redundancy across sections, and missing or inconsistent guideline coverage in your draft, ensuring the formal Design Doc maintains high quality.

Can I transition from a design doc directly to a project plan?

Yes, the skill guides safe transitions to create-plan once your design topic is settled. It supports workflows from design discussion through plan creation, ensuring the rationale and architectural context carry forward correctly.