writing-design-plans_skill

Overview

This skill completes a design document by appending the validated design body, generating the Acceptance Criteria, Summary, and Glossary, and committing the result to docs/design-plans/. It is intended to run after brainstorming and investigation phases so the file created in that workflow is extended into a full, archival design plan. At start it announces: "I'm using the writing-design-plans skill to complete the design document."

How this skill works

The skill reads the existing design file produced in the earlier phase, appends the Architecture, Existing Patterns, Implementation Phases (wrapped in required HTML comment markers), and Additional Considerations sections, then extracts Acceptance Criteria, Summary, and Glossary from the completed body. It ensures phases are sequential, limited to eight, reference exact file paths and component names from investigation, and includes clear "done when" verification criteria. Finally, it commits the updated document for permanence.

When to use it

• After brainstorming and codebase investigation are complete and a Phase 3 design file exists.
• When you need an archival, directional design that other teams can reference later.
• Before creating implementation plans so phases are discoverable and parsable.
• When contracts (APIs, types, schemas) must be defined but not implemented.
• When you need a single source of truth for component responsibilities and dependencies.

Best practices

• Keep phases focused and sequential; target 5–8 phases and never exceed 8 without a note.
• Use exact component names and file paths found during investigation; avoid task-level detail.
• For any contract other systems depend on, fully specify request/response shapes or types.
• Make each functionality phase include tests that map to specific Acceptance Criteria.
• Generate Summary and Glossary only after the body is complete to ensure accuracy.

Example use cases

• Documenting an OAuth2 service design with component boundaries, token schemas, and verification phases.
• Converting a validated architecture draft into an archival design that other teams can depend on.
• Splitting a large feature into up to eight phased deliverables so implementation plans can consume them.
• Capturing data flow, system boundaries, and file paths for a service redesign without including implementation code.