founding-engineer-workflow

Implement features from design docs. Use when (1) user references a design doc from docs/design_docs/, (2) user says "build feature" or "implement feature", (3) user references an existing impl plan from docs/for_ai/plans/. Creates implementation plan from design doc if none exists, then builds.

Bug fixing workflow. Use when (1) user reports a bug, (2) user says "fix bug" or "/fix-bug", (3) debugging failing behavior. Reproduce, fix at the right layer, run tests, open PR, resolve comments, log the task. Add a test only when it captures the bug through observable behavior.

Grade shipped product bets against what their discoveries predicted — pull each registered metric from its source of truth, walk the watch items, verdict every falsification line. Use when (1) user says "/outcome-review", "did it work", "grade our bets", "outcome review", (2) a month has passed since the last review, (3) any outcomes-register row's first check date has passed.

Interview a team member to produce a problem-first proposal — the intake artifact for /sdlc and /adhoc-fullstack-feature. Use when (1) user says "/proposal", "write a proposal", or "pitch", (2) a feature request arrives as a sentence and needs shaping before discovery, (3) someone wants to raise a problem or opportunity for the product pipeline.

Triage and resolve PR review comments — from the /ship-pr review agents (security, design, conventions, bug-hunter, data-migration), from humans, or both. Verify each finding, fix or push back, reply on every thread. Use when user says "/resolve-pr-comments" or asks to resolve PR comments.

Ship a finished slice of work as a PR — open a draft PR, run the review-agent sweep (agents comment inline on the PR), triage every finding, then mark ready. The agents replace the external review bot as the review authority. Use when (1) a workflow skill says "ship with /ship-pr", (2) user asks to open a PR for completed work, (3) work on a branch is built + tested and needs review.

Mine first-party sources for problems nobody raised — public reviews, intake capture forms, analytics funnels, trial/churn data, support threads — and turn them into tier-stamped evidence and candidate problem statements. Use when (1) user says "/signals" or "mine signals", (2) a month has passed since the last sweep, (3) a discovery needs user-side evidence and the requester has none.

Lightweight UX thinking for small features. Use when the direction is relatively clear but benefits from sharpening — clarify intent, challenge assumptions, design quickly. Faster than full discovery, but still thoughtful.

Deep UX and product thinking before building features. Use when starting a new feature, redesigning existing functionality, or when asked to think through a problem. Outputs a structured discovery document for frontend design.

Build verified, interactive visual explainers for code under review — artifacts where the reviewer operates the behavior instead of reading about it, plus Mermaid sequence diagrams derived from the codebase. Use when (1) the user asks to visualize or explain a method, flow, module, or PR ("explain X in an artifact", "visualize this", "diagram this flow", "how does X route/decide"), (2) a review needs behavior made visible — routing decisions, state transitions, before/after semantics, (3) the user asks for a sequence diagram of how services call each other.

Write tests from existing scenarios and implementation. Use after /plan-tests and /build-feature to (1) convert test scenarios to actual tests, (2) detect gaps between scenarios and implementation, (3) run and report results.

Structured critique in two modes — discovery mode for UX discovery documents (run by a fresh-context agent as the ux-discovery critique gate), visual mode for rendered UI, mockups, and React components.

Build production-grade, polished frontend interfaces. Use when implementing features after UX discovery, building new pages/components, or creating demos. Transforms discovery documents into memorable, well-crafted experiences.

Capture visual evidence for a PR with frontend work — a screenshot per relevant state (empty, loading, error, populated), a GIF of the key interaction end to end, before/after where behavior changes — from the branch's final state, pushed to the pr-evidence branch and embedded in the PR body. Use when (1) /ship-pr or a workflow skill calls for PR evidence, (2) user asks to attach screenshots/GIFs to a PR, (3) UI code changed after evidence was captured (re-capture).

Targeted UX addition to a shipped feature. Use when users give feedback requesting a small addition to an existing feature — a new section, a new column, a new action — with no backend change or a minimal one. Reads existing code first, asks 1-3 questions, then designs the addition.

Lightweight workflow for small features that don't need the full feature lifecycle (no design doc, no parallel worktrees). Tests still go through plan-tests + write-tests, but split across two fresh sub-agents so they're not written by the implementer. Use when (1) user says "/adhoc-feature", (2) user says the work is small/quick/adhoc, (3) the change is hours of work, not days.

Drives a feature that spans the backend repo and the frontend repo, UX-first across both. Runs /ux-discovery-lite with a cheap HTML preview → a frontend demo → a short backend design doc, with a hard user-alignment checkpoint after each before any production code; then builds the backend, runs the two-agent test split, wires the UI to the real API, verifies the flow visually, ships two cross-linked PRs. Use when (1) user says "/adhoc-fullstack-feature", (2) a feature needs both an API and a UI, (3) it's hours of work across both repos, not days.

The full feature lifecycle for a big fullstack feature across the backend repo and the frontend repo. Full /ux-discovery → a complete design doc (narrative sections + /design-schema, /design-api, /design-components, each agnostically reviewed) → /build-feature → two-agent tests → wire + visual verify → two cross-linked PRs. Iterative and collaborative — the agent does the work, you sign off every gate. Use when (1) user says "/sdlc", (2) a feature is large enough to need a real design doc and days of work, (3) it spans API + UI. For small work, use /adhoc-fullstack-feature instead.

Draft the API design section of a design doc — endpoints, request/response shapes, domain errors — in one pass with a rationale per contract, then an agnostic review. For big features in the design phase. Use when (1) user says "/design-api", (2) designing the HTTP contract for a new feature, (3) writing the API design section of a docs/design_docs/ doc.

Draft the Components design section of a design doc — modules, service interfaces, data flow, invariants — in one pass with a rationale per component, then an agnostic review. For big features in the design phase. Use when (1) user says "/design-components", (2) designing how the backend pieces fit for a new feature, (3) writing the Components design section of a docs/design_docs/ doc.

Draft the Data design (schema) section of a design doc — entities, keys, indices, constraints, migrations — one piece at a time, each with a rationale, then an agnostic review. For big features in the design phase. Use when (1) user says "/design-schema", (2) designing the data model for a new feature or a real schema change, (3) writing the Data design section of a docs/design_docs/ doc.

Create test scenarios from design docs BEFORE implementation. Use when (1) given a design doc and asked to plan tests, (2) user says "plan tests" or "/plan-tests", (3) preparing test coverage for a new feature, (4) reviewing a design for testability gaps. Outputs GIVEN/WHEN/THEN scenarios to catch edge cases and missing requirements before code is written.

Write technical write-ups for completed features/projects. Use when (1) user asks to document a feature or project, (2) user says "write-up" or "/project-writeup", (3) after completing a significant implementation. Produces factual engineering write-ups that record what was built, how it works, what broke, and what was learned - NOT a duplicate of design docs or implementation plans.

Verify frontend work visually in Chrome. Use after implementing or modifying UI to take headless screenshots at multiple viewports, read them to analyze visual correctness, and catch issues before the user has to.

Find gaps in design docs. Use when reviewing requirements, specs, or PRDs before implementation. Identifies missing edge cases, unclear business rules, and scenarios the design should address but doesn't.