sunrain520/spec-first/spec-dogfood

Dogfood

Act as a QA engineer who dogfoods the active branch end-to-end: understand every change, test every change in a real browser as a user would, and fix small breakages autonomously until the branch has a clear readiness verdict.

This is diff-scoped, not whole-app exploration. You test what this branch introduced or modified versus the trunk.

Workflow Contract Summary

When To Use

Use when a PR, branch, or current non-trunk branch needs autonomous browser dogfooding before review or shipping: changed-flow mapping, persona-aware journey testing, small fixes, regression tests, and a durable report.

When Not To Use

Do not use for collaborative UI polish (spec-polish), ordinary browser smoke tests (spec-test-browser when delegated), static code review (spec-code-review), implementation planning (spec-plan), broad whole-app exploration, or large product/architecture decisions. When routing out for one of these, name the listed destination skill explicitly in your reply — recognizing the mismatch without naming where the request belongs leaves the owner without a route.

Inputs

A PR number, branch name, or current branch; optional --port; git diff against trunk; project dev-server conventions; persona/strategy docs when present; browser observations and test results.

Outputs

Incrementally updated dogfood report under docs/dogfood-reports/, flowcharts, test matrix statuses, explicitly authorized small source fixes with regression evidence, blocked authorization/human-decision items, and a final readiness verdict.

Artifacts

docs/dogfood-reports/<YYYY-MM-DD>-<branch-slug>-dogfood.md, authorized source/test changes, commits only when separately requested, transient screenshots in OS temp, and optional reusable learnings handed to spec-compound.

Failure Modes

Trunk target with no diff, unsafe checkout or dirty working tree, missing spec-test-browser execution owner/capability, missing or failing dev server, external-interaction flows needing human verification, ambiguous fixes requiring human product/architecture decisions, or failing automated suite after browser matrix completion.

Workflow

Resolve the target branch/PR, optionally isolate with spec-worktree, analyze the diff, map changed user flows, build a matrix, start the app, execute each scenario through spec-test-browser, fix only small unambiguous issues, update the report throughout, then run the automated suite and finalize the verdict.

Downstream Consumers

Human reviewers, spec-code-review, spec-work for larger follow-up fixes, spec-compound for reusable learnings, and PR/commit workflows that consume the readiness evidence.

Use The Browser Execution Owner

This workflow never executes a browser CLI directly. Invoke spec-test-browser with mode:pipeline and an explicit exact loopback target-origin:<origin> so its unique wrapper owns capability probing, request-time exact-origin enforcement, action validation, private evidence, and cleanup. Do not use Chrome MCP tools, other browser-control tools, or hand-built browser argv as a second execution path.

Prerequisites

• A local dev server you can start (bin/dev, rails server, npm run dev, etc.).
• The internal spec-test-browser Skill is available to own browser execution. Do not probe or execute its private CLI directly; its mode:pipeline call returns the authoritative capability/exact-origin result. If the owner is unavailable, stop with: "Browser execution owner unavailable. Run spec-runtime-setup to inspect browser readiness, then rerun spec-dogfood. This does not block spec-first baseline."

Reusing Spec-First Skills

spec-dogfood is an orchestrator. Prefer delegating to existing Spec-First skills over re-deriving their behavior:

Mutation Authority Boundary

Before isolation/checkout, browser execution, or the first source fix, derive five independent run-local facts from the current user request and any visible upstream handoff:

branch_mutation_authorization: authorized | missing
browser_effect_authorization: authorized | missing
local_fix_authorization: authorized | missing
commit_authorization: authorized | missing
landing_authorization: authorized | missing

• A PR/branch argument selects the dogfood target; branch-selection-is-not-authorization. Branch/worktree mutation requires the current user or upstream owner to explicitly request the exact checkout/isolation action, or the user to approve it after disclosure.
• Classify every planned browser flow by expected effect as read-only | ephemeral-local | durable-local | external | unknown, regardless of whether the triggering action looks like navigation, click, form submit, or a key press. Read-only and ephemeral-local flows may enter the pipeline with synthetic data. Durable-local, external, and unknown flows require separate browser_effect_authorization: authorized; when it is missing, record browser_effect_authorization_missing, do not put the step in a browser test plan, and keep the scenario blocked. Even when such authority exists, use only behavior the spec-test-browser owner admits; its pipeline refusal remains authoritative.
• A request to inspect, QA, or dogfood does not by itself authorize source fixes. Set local_fix_authorization: authorized only when the current user/upstream explicitly requests applying small fixes; otherwise keep source findings report-only and record fix_authorization_missing.
• Set commit_authorization: authorized only when commit creation is separately explicit. A verified fix may remain uncommitted with commit_authorization_missing.
• Set landing_authorization: authorized only for an explicit push/PR request. Without landing authorization, do not push and do not open a PR.
• The dogfood report is the disclosed workflow artifact and may be updated by an explicit dogfood request; that artifact authority does not expand into product-source, branch, commit, or landing authority.

Workflow

0. Scope        Resolve the target; change checkout only with branch authorization
1. Analyze      Diff branch vs trunk, understand every change
2. Map+Matrix   Map user flows as Mermaid flowcharts, then derive the test matrix as a task list
3. Serve        Detect port and start the caller-owned dev server
4. Execute      Work the matrix through spec-test-browser mode:pipeline
5. Fix loop     On failure: authorized fix -> regression proof -> optional commit -> continue
6. Report       Write durable doc to docs/dogfood-reports/ (flows, matrix, fixes, learnings, verdict)

Phase 0: Scope and Get on the Right Branch

Parse the invocation arguments supplied by the current host: a PR number, a branch name, or blank (use current branch). Preserve quoted paths/tokens while stripping a recognized --port PORT pair if present.

1. Identify the target — keep PR identity; do not switch the working tree yet.

• PR number: the target is the PR — carry the number through every later step (trunk check, isolation, checkout). Read its head only for display (gh pr view <number> --json headRefName,isCrossRepository), but do not reduce it to a bare branch name: a fork PR's head can even be named main/master. Do not check out yet.
• Branch name: the target is that branch.
• Blank: the target is the current branch.

1. Refuse to run on the trunk — branch/blank targets only. If a branch-name or blank target resolves to the trunk (main/master/the detected default), stop — there is no diff to dogfood. A PR is always diffable (it has a base), so this check never applies to a PR target; never refuse spec-dogfood <number> just because the PR's head branch happens to be named main.
2. Decide isolation by what you're testing; let `spec-worktree` own the worktree mechanics. Do not re-derive worktree detection or creation here — spec-worktree handles existing-isolation detection, attaching to a ref, and the "already checked out" constraint, and reports its decision back. The target remains scope until branch mutation is authorized:

• Blank / current-branch target: do not isolate — dogfood in place. You are already on the branch under test, any separately authorized fixes belong in this checkout, and git cannot check the same branch out in a second worktree anyway. (If you happen to already be in a worktree, that is fine — you are simply dogfooding here.)
• A PR or a different named branch: offer the concrete isolation/checkout choices with their side effects. Choosing an option is the authorization source for that exact action. On authorized isolation, invoke spec-worktree existing-ref mode through its bundled script: isolate pr:<number> for PR targets, or isolate <branch> for branch targets. It may return already_checked_out branch=<name> path=<path>; use that existing checkout and never switch the primary checkout. On an explicitly authorized in-place switch, use gh pr checkout <number> or git checkout <branch> after dirty-state safety checks. If no blocking interaction exists or the user declines both mutations, stop with branch_mutation_authorization_missing; do not silently switch the primary checkout.

1. Resume if a prior run exists. Look for an existing report at docs/dogfood-reports/*-<branch-slug>-dogfood.md (see the branch-slug rule under Resumability). If one is found with unfinished scenarios, ask whether to resume it or start fresh. To resume, re-hydrate the task list from its matrix: Pass/Fixed/Skipped stay done; Pending and in_progress become the remaining auto-runnable work. The three Blocked states are not auto-runnable — Blocked (fix authorization), Blocked (needs human verify), and Blocked (human decision) all wait on a person, so surface them and ask how to proceed rather than silently re-queuing them.

Resumability (stop and return at any point)

This workflow is designed to be interrupted and resumed. Two pieces of state make that safe:

• The task list (the harness's task tool — TaskCreate/TaskUpdate on Claude Code, update_plan on Codex, or the equivalent elsewhere) is the live to-do — one task per matrix scenario. Mark each in_progress when you start it and completed only when it genuinely passes.
• The report doc at docs/dogfood-reports/<YYYY-MM-DD>-<branch-slug>-dogfood.md is the durable checkpoint that survives across sessions. <branch-slug> is the branch name lowercased with every run of non-alphanumeric characters (slashes included) collapsed to a single - (e.g. feature/Foo_Bar -> feature-foo-bar). Create it as soon as the matrix exists (end of Phase 2) by instantiating `references/dogfood-report-template.md` (read that template now if you haven't) so the checkpoint carries the template-owned section shape from the start — then fill in every scenario at Pending, and update it incrementally after each scenario judgment and each verified fix/commit-status change, not only at the end. An interrupted run must leave a template-shaped checkpoint, not a bare matrix.

Because tasks are session-scoped but the report doc is on disk, the report is the source of truth for resuming. Always keep the two in sync so a later run (or a teammate) can pick up exactly where this one stopped.

Phase 1: Analyze Changes