hk-mock-first

/hk-mock-first — Mock-First, Layer-by-Layer Feature Development

The traditional approach — build the plumbing, wire the API, then hope the UI works — inverts the feedback loop. You discover experience problems after committing to implementation choices. This skill inverts the flow: validate the experience first with realistic mocks, then progressively replace mocks with real code, one complexity layer at a time.

Why this matters: A feature that "works" but feels wrong is more expensive to fix than one that was never built. Mock-first means the human curates the experience before any plumbing exists. This directly serves the philosophy tenet of Taste as a Filter — the system produces options, the human filters. And Good Enough — you don't over-engineer layers that haven't been validated yet.

Context

<feature_context> $ARGUMENTS </feature_context>

If the context above is empty or unclear, ask the user:

1. What feature or change are you building?
2. Which user-facing interfaces does it touch? (UI pages, CLI output, API responses that drive UI)
3. Where should the workspace live? (suggest docs/mock-first/<feature-slug>/)

The Workspace

Everything lives on disk. The workspace is the product, not temp files — it's the organized record of what was mocked, what was accepted, and what's been deepened. It also serves as the resumption anchor: if the conversation compacts or a new session starts, the workspace contains everything needed to continue.

docs/mock-first/<feature-slug>/
├── tracker.md                  # Live state (the resumption anchor)
├── surface/
│   ├── interface-map.md        # All user-facing interfaces this feature touches
│   ├── mock-data/              # Actual mock data files (JSON, fixtures, factories)
│   ├── mock-components/        # Mock UI components, stubs, or test pages (if applicable)
│   ├── states.md               # All UI/interface states catalogued
│   └── acceptance.md           # User's acceptance notes + screenshots
├── layer-1/
│   ├── boundary.md             # What this layer is, where the complexity boundary sits
│   ├── test-plan.md            # TDD: tests to write before implementation
│   ├── changes.md              # What changed (files, diffs)
│   └── verification.md         # Tests pass + interface still works
├── layer-2/
│   └── ...
└── summary.md                  # Written when feature ships (or when pausing long-term)