skills.rest
Zaba505
Zaba505COMMUNITY
Explore all skills by this author →
WebsiteGitHub

plan-tech-design

Compose skeleton tech-design documents from accepted ADRs and file GitHub issues per component and gap.

1|Updated Mar 7, 2023
Search Tags:#planning#architecture#adr#github issues#audit trail#hugo#tech design
One-click install
npx skills add https://github.com/Zaba505/infra --skill plan-tech-design-zaba505
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: plan-tech-design
Source: https://github.com/Zaba505/infra/tree/main/.claude/skills/plan-tech-design
Command: npx skills add https://github.com/Zaba505/infra --skill plan-tech-design-zaba505

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes assets (resource) components.

What problem does it solve? After all ADRs for a capability are accepted, teams still need a navigable bridge between architecture decisions and implementation work. This Skill composes a skeleton tech-design.md that maps every technical requirement through an ADR to a named component, surfaces gaps instead of papering over them, and files one GitHub issue per component and per gap so follow-up design work is tracked. ## Core Features & Use Cases - Skeleton tech-design composition: Generates tech-design.md from a template with an overview, Mermaid component diagram, component inventory, data & state summary, and a TR → ADR → component audit trail. - Gap surfacing and gating: Refuses to run when tech-requirements are unreviewed or ADRs are still proposed, and files gap issues for uncovered TRs, missing realizations, or unspecified implementation details. - GitHub issue orchestration: After explicit user approval, files component issues (for define-component-design) and gap issues via gh CLI, wires blocked-by relationships, and places items on the project board with milestone and Area fields. - Use Case: After accepting ADRs 0001–0007 for a self-hosted application platform capability, run this Skill to produce tech-design.md and automatically file tracked issues for each service, Terraform module, and unresolved gap. ## Quick Start Compose the tech design for the capability in docs/content/capabilities/self-hosted-application-platform now that all its ADRs are accepted.

Frequently Asked Questions about plan-tech-design

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

FAQPage Schema
How do I compose a tech design document from accepted ADRs?▼

Invoke this Skill once every ADR under the capability's adrs/ directory has status accepted and tech-requirements.md has a fresh reviewed_at date. It walks each ADR's Realization section, clusters components, and writes tech-design.md with an inventory and audit trail.

What happens if some ADRs are still proposed when composing a tech design?▼

The Skill refuses to compose and lists the proposed ADRs blocking the run. You must accept them via the define-adr skill or revise them first, because composing a design against unsettled decisions is explicitly disallowed.

Does the tech-design.md include API endpoints and database schemas?▼

No. The document is a skeleton containing overview, component inventory, and the requirement audit trail only. Per-component detail like endpoint paths, table columns, and sequence diagrams is deferred to per-component design docs authored via define-component-design.

How are gaps in requirements or ADRs handled during composition?▼

Each gap is stated specifically, classified by resolution type (amending TRs, amending ADRs, per-component spec, or inline answer), and filed as a GitHub issue titled story(gap). The tech design is not considered complete until all gap issues are resolved.

Can this Skill file GitHub issues without user approval?▼

No. It mirrors back the component list, gap list, and audit-trail counts, then waits for explicit approval before running gh issue create. It also asks which milestone and project board Area value to apply rather than inventing them.

Why does the audit trail require every TR to appear?▼

The TR → ADR → component table is the traceability guarantee of the design. If any TR lacks an ADR or realization, the Skill treats it as a gap and routes back to plan-adrs or define-technical-requirements instead of inventing coverage in prose.

Related Skills

Explore More Software Engineering Skills→
akvoakvo
2

bmad-architect

Design system architectures and document decisions with Architecture Decision Records.

Official
Advanced
not-aninot-ani

convex-component-authoring

Build and publish self-contained Convex components with isolated schemas, functions, and types.

Community
Intermediate
rodolfochiconerodolfochicone
19

rc-spec

Interviews users to produce PRD, tech spec, and ADR documents.

Community
Advanced
mrrtsmrrts
1

batch-hypotheses

Bundle multiple prompt experiments into a single ChatGPT call for comparative synthesis.

Community
Advanced