nq-design

name	nq-design
description	Guide the tech design discussion and design doc drafting for a feature. Use when starting steps 3-4 of the feature process.
user-invocable	true
argument-hint	Feature name or requirements doc path (e.g., "XP from history" or "docs/requirements/encounters.md")

NQ Tech Design Process

This skill guides steps 3 (Tech Design Discussion) and 4 (Design Doc) of the feature process defined in CLAUDE.md.

Input: A feature name, requirements doc, or conversation context describing what we're building.

---

Step 1: Read Context

Before any design discussion, read:

1. The requirements doc (if one exists) — line by line. Flag any place where a design decision might deviate.
2. DATA_MODEL.md — understand current entities, relationships, lifecycle rules.
3. docs/mechanics.md — understand current user-facing behavior.
4. Relevant source code — trace the existing functions that touch the feature area.

Step 2: Tech Design Discussion

Talk through how to build it. Cover:

1. Entities and relationships — what data structures change or are added?
2. Data flow — how does data move from user action to storage to display?
3. Trade-offs — what are the options, what do you recommend, and why?
4. Vertical slices — each implementation step must deliver something the user can functionally test, not "backend then frontend." Don't separate backend from frontend into different steps when the frontend is the primary way to verify the backend works.

Surface genuine questions and gaps. Don't default to "no questions, ready to build." Spend real effort thinking through edge cases before saying there aren't any.

Step 3: Pre-Draft Checklist

Before drafting the design doc, verify you can answer each of these. If not, raise the gap.

Read Path Analysis

• What queries or display functions change?
• Who consumes this data? (UI surfaces, CLI commands, external tools)
• What existing behavior must be preserved?

Write Path Analysis (CRITICAL — this is where design gaps become implementation bugs)

• What functions write the data being changed? Enumerate them.
• For each write function: what is its current structure? What changes?
• What transactional boundaries exist? Will they need restructuring?
• Are there multiple write paths that must stay consistent? (e.g., quest completion, saga bonus, campaign bonus all following the same pattern)
• What happens during migration for existing users? Does it run automatically on launch?

Consumer Analysis

• What UI surfaces display this data?
• What CLI commands read or modify it?
• Are there external consumers (nq-companion, scripts)?
• Do any consumers need corresponding changes?

Edge Cases

• What happens with empty/NULL data?
• What happens during the transition (old data + new code)?
• Are there ordering or timing dependencies?

Step 4: Draft the Design Doc

Write to docs/design/<feature-name>-design.md. The doc must include:

1. Goal — one paragraph.
2. Approach — high-level strategy.
3. Write path changes — enumerate every function that writes affected data, what changes in each, and transactional boundaries.
4. Read path changes — what queries change, what display updates.
5. Migration — what happens for existing users on first launch.
6. Implementation steps — vertical slices, each independently testable. For UI-visible changes, specify which tab/view to test on (e.g., "Quest List tab," "Quest Giver," "Saga tab"). Data that appears on multiple surfaces (e.g., saga steps on both Quest List and Saga tab) should name each surface explicitly.
7. Out of scope — what we're explicitly not doing.

Design Doc Rules

• Implement the requirements, not reinterpret them. If a design decision differs from what was agreed, flag it BEFORE writing the doc.
• Summarize after drafting. End with a conversational summary of the approach and implementation steps so the user can react before we commit to the plan.
• Don't commit without code. Design docs are committed alongside implementation, or when the user explicitly asks for a doc-only commit.

Step 5: Step Spec

After the design doc is approved, write a step spec for the first vertical slice. Scoped to what can be built, tested, and committed in one session. Lives in docs/step-spec.md.