# Hdb:design

> Design a new software feature with a PRD and detailed implementation task list

- Skill: `hughdbrown/hdb-design` (Agent Skill, multi-file: 8 files)
- Install (CLI): `npx skillmds@latest add hughdbrown/hdb-design`
- Raw SKILL.md: https://api.skillmd.com/api/skills/hughdbrown/hdb-design/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: hughdbrown (https://skillmd.com/u/hughdbrown)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/hughdbrown/hdb-design

---


# hdb:design

## Usage

```
/hdb:design <feature description>
```

## Description

Designs a new software feature in five phases (triage → understand → PRD → tasks → write), grounded in the project's actual codebase. Produces two deliverables written to `docs/design/<feature-slug>-{prd,tasks}.md`:

1. **PRD** — overview, goals, acceptance criteria (as test descriptions), technical decisions, design, test strategy, rollback, and implementation stages.
2. **Task List** — test-first steps per stage: tests, code, verification commands, risks.

## Instructions

### Phase 0: Triage

1. **Classify scope** and state reasoning:
   - **Small** (1 file, <50 lines, no new patterns): task list only → skip to Phase 3.
   - **Medium** (2–5 files, existing patterns): PRD + task list → all phases.
   - **Large** (multiple subsystems, new patterns): PRD + task list. Consider splitting into sub-designs.
   - **Ambiguous** (no concrete problem/solution): clarify in Phase 1, then re-classify.

   The feature description is the scope — no tangential improvements or unnecessary abstractions.

### Phase 1: Understand

2. **Clarify (if needed)** using `AskUserQuestion` — only when the description lacks a concrete what or how. At most 3–4 questions: problem/user, constraints, out-of-scope, prior art. If clear, skip to exploration.

3. **Explore the codebase** with parallel tool calls. Every technical decision in the PRD must cite a specific file or pattern discovered here:
   - `Glob("**/*.{go,rs,py,ts}")` → project structure and file layout
   - `Read` build/config files (go.mod, Cargo.toml, package.json) → tech stack and dependencies
   - `Grep` for error handling, test patterns, naming conventions → coding standards
   - `Grep` for feature-related keywords → related existing code
   - For unfamiliar codebases: use `Agent` subagents to explore multiple areas concurrently

4. **Identify integration points.** For each, record: the file path, the function/type involved, and the convention new code must follow (naming, error handling, test style). Flag novel patterns (no codebase precedent) for Phase 2 decisions. Done when every file and convention is named.

### Phase 2: PRD

5. **Write the PRD**:
   - **Overview**: What the feature does and the problem it solves.
   - **Goals / Non-Goals**: Bulleted. Non-goals prevent scope creep.
   - **Acceptance Criteria** (as test descriptions): `TestName`: When X, assert Y. If you can't write a criterion as a test, the design is too vague.
   - **Technical Decisions**: Cite the codebase file/pattern justifying each choice. For novel patterns: present ≥2 options with trade-offs, recommend one, flag for developer. For unknowable runtime behavior: recommend a time-boxed spike.
   - **Design and Operation**: User perspective, system perspective (data flow, concurrency, state), error handling, edge cases.
   - **Test Strategy**: Levels (unit/integration/e2e), infrastructure (fixtures, mocks, temp dirs), key scenarios.
   - **Rollback and Safety**: Can the feature be disabled without data loss? One sentence for trivial features.
   - **Implementation Stages**: Ordered. Each stage: working system, ≤5 files, deliverable verifiable in under a minute.

6. **Present PRD** to the user. Wait for explicit approval before proceeding.

### Phase 3: Task List

7. **Build test-first tasks per stage.** Be specific — name files, functions, types:
   - **Tests**: functions, assertions, fixtures — always first.
   - **Code**: minimum to pass tests (files, functions, config, deps, migrations, API surface as applicable).
   - **Verify**: exact test command.
   - **Risks**: known blockers.

8. **Order tasks** top-to-bottom, no forward dependencies. Note parallelizable tasks.

9. **Validate coverage**: name the task covering each acceptance criterion. Add tasks for gaps.

10. **Present task list** to the user. Incorporate feedback.

### Phase 4: Write Files

11. **Write files** with `Write` tool to `docs/design/` (or ask user). Offer next steps: implement stage 1, commit docs, or refine.

## Implementation Protocol

Per task: (1) write tests (compile but fail), (2) confirm correct failures (add stubs if needed), (3) implement minimum to pass, (4) run tests (green = done; red = fix implementation), (5) lint/format, (6) next task.

**No untested code** — test or delete. Tests are the specification. Never weaken assertions.

## Guidelines

- **Ground decisions** in existing codebase patterns — cite specific files.
- **Isolate risk** — put unknowns and external dependencies in early stages so later work isn't blocked.
- **Be specific** — name files, functions, types. Vague tasks waste time.
- **Flag trade-offs** — present options with pros/cons for the developer.
- **Adapt to scope** — small: 1 stage, no PRD. Large: 5+ stages, consider sub-designs.

## Example

User: `/hdb:design webhook notifications for review completion`

**Triage**: Medium — config, storage, worker, CLI (4 areas), existing patterns.

**Clarify**: "Multiple URLs per repo? Retry logic? Configurable payload format?"

**Explore**: `Glob("**/*.go")` maps structure (12 packages). `Read` on `go.mod` (no HTTP client deps → stdlib is sufficient), `internal/config/config.go` (uses `[[repos]]` TOML array pattern). `Grep("ReviewComplete\|jobDone")` finds the hook in `internal/worker/run.go:142` and state tracking in `internal/storage/jobs.go:89`.

**PRD** (written to `webhook-prd.md`):
- **Overview**: HTTP POST on review completion for external tools.
- **Goals**: Reliable delivery, multiple URLs, verdict in payload. **Non-goals**: payload transforms, auth beyond shared secret, webhook UI.
- **Acceptance Criteria**: `TestWebhookDelivery_SendsPostOnComplete` (POST within 5s), `TestWebhookDelivery_NoConfigNoSend` (no URL → no request), `TestWebhookConfig_ParsesTOML`, `TestWebhookPayload_IncludesVerdict`.
- **Technical decisions**: stdlib `net/http` (no HTTP client deps in `go.mod` — adding one is unjustified for simple POST requests), TOML config with `[[webhooks]]` (matches existing `[[repos]]` pattern in `config.go`), SQLite `webhook_deliveries` table (follows existing `internal/storage/jobs.go` table pattern).
- **Design**: Job done → enqueue per URL → goroutine POSTs and records result.
- **Stages**: (1) Config + storage, (2) Delivery engine, (3) Worker integration, (4) CLI commands.

**User feedback**: "Skip retry for v1." → removed retry section from PRD, simplified stages.

**Task list** (Stage 1):

> **Task 1.1: Config parsing**
> - **Tests**: `TestConfig_WebhookSection` (TOML → structs), `TestConfig_NoWebhooks` (→ empty slice)
> - **Code**: `WebhookConfig` type + `[[webhooks]]` in `internal/config/config.go`
> - **Verify**: `go test ./internal/config/...`

> **Task 1.2: Delivery storage**
> - **Tests**: `TestInsertWebhookDelivery` (insert + read back), `TestListWebhookDeliveries` (count + order)
> - **Code**: Migration in `migrations.go`, methods in `webhooks.go`
> - **Verify**: `go test ./internal/storage/...`
> - **Risks**: File-backed SQLite for WAL — use `t.TempDir()`.

**Validate**: `TestWebhookConfig_ParsesTOML` → Task 1.1, `TestWebhookDelivery_SendsPostOnComplete` → Task 2.1. All covered. `Write` to `docs/design/`. **Next**: implement stage 1.