Spec Polish

Polish

Start the dev server, open the feature in a browser, and iterate. You use the feature, say what feels off, and fixes happen.

Workflow Contract Summary

When To Use

Use when a feature or branch is ready for hands-on browser polish: start its dev server, inspect the feature in browser, and make iterative UI/UX fixes from direct feedback.

When Not To Use

Do not use for initial requirements, implementation planning, non-browser backend work, static code review, broad visual audits, or MCP setup/repair beyond the browser helper handoff. When routing out for one of these, name the destination skill explicitly in your reply (static code review belongs to spec-code-review) — recognizing the mismatch and then doing the excluded work anyway is adopting the wrong workflow, not a helpful fallback. A direct user request to do the excluded work inside this workflow ("帮我静态审查一下,不用起服务") is still a routing-out condition: name spec-code-review, do not run the review here — not even a partial, "quick pass" version of it.

Inputs

A PR number, branch name, or current branch; project dev-server conventions; feature URL/route when known; user feedback from browser inspection.

Outputs

Running local dev server URL, browser handoff, authorized scoped polish edits, verification notes, and an explicit commit status.

Artifacts

Authorized source edits in the user's project, dev-server log in temp space, optional browser screenshots/inspection notes, and a final commit only when separately authorized.

Failure Modes

Wrong branch, main/master branch, missing branch-mutation authority, missing dev-server command, unresolved port, server startup failure, browser helper unavailable, or user feedback requiring upstream product/design decisions.

Workflow

Select the branch, start the dev server, resolve the browser handoff, iterate on user-reported polish issues, and stop when the user says the loop is complete.

Downstream Consumers

The user reviewing the browser result, spec-work for deeper implementation follow-up, and release/review workflows that consume the final branch changes.

Mutation Authority Boundary

Before checkout or the first source edit, derive four independent run-local facts from the current user request and any visible upstream handoff:

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

• A PR number or branch name selects review/polish scope; it does not authorize checkout. Set branch_mutation_authorization: authorized only when the current user or upstream owner explicitly requests the switch/worktree, or the user accepts the concrete checkout/isolation action after it is disclosed.
• Set local_fix_authorization: authorized only when the current user explicitly requests polishing/fixes or the upstream handoff explicitly owns local apply. A route recommendation, branch target, or tool permission is not mutation authority.
• Set commit_authorization: authorized only for an explicit commit request. done is a completion signal, not commit authorization.
• Set landing_authorization: authorized only for an explicit push/PR request. Without landing authorization, do not push and do not open a PR.
• These facts are non-transitive: local fixes do not imply checkout, commit, or landing; commit does not imply landing.

Phase 0: Get on the right branch

1. If blank, use the current branch.
2. If a PR number or branch name was provided, resolve it as scope and probe for existing worktrees without switching. When it is not the current checkout:
   • with branch_mutation_authorization: authorized, use the explicitly approved existing-worktree/checkout action;
   • otherwise stop before mutation with branch_mutation_authorization_missing, name the current and requested refs, and ask the user to switch themselves or authorize the exact action.
3. Verify the selected checkout is not main/master.

Phase 1: Start the dev server

The scripts below ship in this skill's scripts/ directory. The Bash tool's working directory is the user's project, not the skill directory, so a bare scripts/<name> path will not resolve — invoke each by the skill's own absolute path. Every runnable block below sets SKILL_DIR inline (shell state does not persist between Bash tool calls, so each command must carry it); replace the <absolute path …> placeholder with the directory you loaded this spec-polish SKILL.md from before running.

1.1 Check for .claude/launch.json

SKILL_DIR="<absolute path of the directory containing this SKILL.md>";
bash "$SKILL_DIR/scripts/read-launch-json.sh"

If it finds a configuration, use it — the user already told us how to start the project.