Feature Skill

Phase 0.0 — Issue Claim (if invoked with #N)

When this section runs: only if the invocation provides a GitHub issue number, e.g. /feature #1153. Skip entirely for /feature <freeform-spec> (no issue to claim — proceed directly to Phase 0).

1. Read the issue state

gh issue view <N> --json number,title,state,body,createdAt,assignees,comments

If the command fails (issue not found, network down, missing scope) → STOP and surface the error to the user before proceeding. Do not silently fall through to the claim step.

If state is closed → STOP, ask the user (working on a closed issue is almost always wrong).

2. Detect collision

Inspect assignees[] and the most recent comment whose body starts with WIP — (em dash U+2014, not a hyphen — only the canonical em-dash form is detected; hyphen variants WIP - are silently ignored):

Situation	Action
assignees contains @me (current GitHub user)	Continue silently — resuming own work
Most recent WIP — comment by @me (any age)	Continue silently — resuming own work
assignees empty AND no WIP — comment from anyone	Proceed to claim (step 3)
assignees contains user ≠ @me	STOP — surface "Issue #N already assigned to <user>. Take over? (y/N)". Wait for explicit user confirmation.
Most recent WIP — comment by user ≠ @me AND <24h old	STOP — surface "Issue #N has fresh WIP from <user> (started <ts>). Collision likely. Continue anyway? (y/N)". Wait.
Most recent WIP — comment by user ≠ @me AND >24h old	Stale claim — surface "Issue #N has stale WIP from <user> (started <ts>, >24h). Reclaim? (y/N)". Wait.

"Current GitHub user" = gh api user --jq .login. Run inline each time @me is compared (the call is fast and read-only).

3. Claim

If detection passed (or user confirmed override), run both commands:

gh issue edit <N> --add-assignee @me

gh issue comment <N> --body "WIP — session $(date -u +%Y%m%dT%H%M%SZ)-$(uuidgen | head -c 8), branch <branch-name>, started $(date -u +%Y-%m-%dT%H:%M:%SZ)"

Where <branch-name> is the branch this /feature invocation will use (planned name, even if not yet created). If the branch isn't decided yet, use branch TBD. Posting a follow-up comment with the real branch name after /pull-request creates it is best-effort manual — the linked PR superseding the WIP comment is what matters in practice.

4. Aged-scope gate (re-validate before implementing)

The issue body is the primary scope source — read it, not just the title (issues are often filed well ahead of execution, and the intended scope lives in the description). Before coding:

• If the issue is old (createdAt older than ~7 days), or its body references files, symbols, or routes that no longer match the current codebase → re-validate the scope: check the referenced code, summarize the drift ("the issue says X, the code now does Y"), and present it to the user for confirmation before proceeding. A stale scope implemented as-written ships against a codebase that has moved.
• Fresh issue with matching references → continue silently.
• If the user aborts at this gate, roll back the FULL claim from step 3 — gh issue edit <N> --remove-assignee @me AND delete the WIP — comment just posted (gh api -X DELETE repos/<owner>/<repo>/issues/comments/<comment-id> — capture the id when posting, or take the last own WIP — comment). Leaving the comment behind would make step 2 treat the aborted claim as resumable on the next run.

4b. Non-interactive invocation (orchestrated runs)

When the invoker's brief declares a non-interactive run (an orchestrating agent executes the issue headlessly — no human present to answer), every STOP-and-ask in this skill becomes a structured final line instead of a question:

Interactive behavior	Non-interactive replacement
Collision prompt (any y/N row of the table above)	Emit SKIP: collision — <detail> and stop
gh command failure (step 1) or state == closed	Emit STOP: claim — <error> and stop
Aged-scope drift confirmation (step 4)	Emit STOP: freshness — <drift summary> and stop
Phase 0 step 1b: no red command for a bug	Emit STOP: repro — <what was tried> and stop
Phase 0 "Present plan & wait for validation"	Satisfied by the issue body when the brief states the scope was validated upstream; insufficient scope → emit STOP: scope — <gap> and stop

Never wait on a prompt in a non-interactive run. If the stop happens after the claim (step 3) already landed, roll the claim back first (step 4's rollback: --remove-assignee + delete the WIP — comment) so the aborted attempt doesn't read as live work on the next run. Interactive sessions keep the exact behavior above.

5. Proceed to Phase 0

Continue to scope analysis below.

---

Phase 0 — Scope Analysis (interactive, before coding)

1. Identify target module

• Read CLAUDE.md for project conventions and stack patterns.
• Read ERRORS.md for known bugs and non-obvious pitfalls to avoid before coding.
• Which module? Default to ONE unless justified.
• If the module doesn't exist → run /create-module to scaffold it first, then continue.

1b. Bug fix? Prove it before you fix it

When the issue is a bug (broken, throwing, wrong output, slow), do this before the plan — a theory built before a red command is the failure this step prevents. The repro (a test or a script) and temporary probes (tagged logs, a value changed to test a guess) are not feature code: they are allowed before the plan is validated, and probes are reverted before Phase 1.

1. One red command. Build one command that drives the real code path and fails on the user's exact symptom — a failing unit test at the closest seam (npm run test:unit, Vitest), else a browser check of the page, else a small script. Run it and keep the output. No red command → no theory: list what you tried and ask for an artifact (log, payload, steps); headless, with or without an issue number, emit STOP: repro — <what was tried> instead (§4b).
2. Shrink it. Cut inputs, config and steps one at a time, re-running after each cut, while it stays red. What is left becomes the regression test.
3. 3–5 guesses, each testable — "if X is the cause, changing Y makes it pass". Test them one variable at a time; the ranked list and the confirmed cause go into the plan you present below (headless: into the PR body, since no plan is presented). Tag temporary logs with one prefix ([DEBUG-xxxx]) and grep them out before the PR.
4. Then, in Phase 1, fix behind the test. The regression test fails first, then passes; re-run the original red command. Name the confirmed cause in the PR body; a non-obvious one also goes to ERRORS.md.

Skip only for a trivial fix whose cause is already proven (typo, wrong constant seen in the code).

2. Analyze flows & edge cases

For each user-facing flow this feature creates or modifies, identify:

• Happy path — standard success scenario
• Error path — what fails, what does the user see?
• "Last one" edge — last owner, last org, last member
• Retry edge — can the user retry after failure/rejection?
• Multi-user impact — who else is affected?

3. Check completeness

• Will every backend API endpoint have a corresponding UI?
• Every UI action has visible feedback (success + error)
• Feature works without mailer / without organizations enabled

3b. Minimal-code ladder (run before presenting)

Challenge every mechanism this change would introduce — a store field, a persisted flag, a composable, a wrapper component, a new field in the API contract. Stop at the first rung that holds:

0. Does a product decision remove it? — accept the cost, accept the failure, do nothing, or surface it to the user. This rung holds only if the mechanism then disappears; if the product still needs it (a message still has to be rendered, a state still has to be held), keep going down the ladder.
1. Already in this codebase? — reuse the composable, store or component.
2. In the standard library? — use it.
3. A native platform feature? (HTML input validation, CSS, a framework or design-system built-in) — use it.
4. An already-installed dependency? — use it.
5. One line, a constant, or config? — make it that.
6. Only then: build it, minimal.

Persisted state is the expensive rung. State that outlives the session — a persisted store slice, a localStorage key, an API field the backend retains and replays back — encoding a policy (a preference, a cap, a memo of a past failure) is not a code choice: code is deleted, persisted state has to be migrated or read forever. A transient request or response field is not this; only state that is retained or restored counts. Rung 0 is mandatory for it, and it needs an explicit, blocking user confirmation in §4 before it is built — a yes on that specific state, never implied by the general plan validation.

Never traded away (lazy ≠ negligent): understanding the problem before picking a rung, validation at trust boundaries, error handling that prevents data loss, security, accessibility, and anything the user explicitly asked for.

4. Present plan & ask questions

STOP and present to the user:

• Flows identified (happy + error + edge cases)
• UI elements needed
• Ladder outcome (§3b) — the selected rung first (<rung> — <what it resolves to>, e.g. 1 reuse — existing composable), then one line per rejected mechanism (<mechanism> — simpler option <X> rejected because <reason>). A change that adds a mechanism and rejects nothing means nobody looked.
• Persisted state, if any — name it and wait for an explicit yes on it; a general "plan validated" does not cover it, and it is not built without that yes.
• Open questions or scope decisions

Wait for user validation before coding. (Non-interactive runs: Phase 0.0 §4b — a validated issue body satisfies this step; never wait.)

Phase 1 — Implementation

5. Module structure

Follow layered approach: UI → Store → API. Each layer references only the one below.

• Use Vue 3 Composition API + Vuetify 4
• Follow /naming conventions
• Follow existing module patterns
• When an edge case or bug affects more than one call site, fix the root cause once in the shared function (store action, helper, service) — not a guard repeated at each caller.

Pass-through store actions: a store action that only forwards an API call (one request, no branching, no derived computation, and no state change after the await — a reset or assignment after the call needs its error-path test, since coverage stays 100% while the failure case goes untested) needs no dedicated test beyond being exercised once in the module's store test — skip the separate happy/error-path block for it. Keep the store's own test file; only the per-action boilerplate goes. This is reachable under this repo's per-file coverage thresholds (vitest.config.js) without lowering or excluding anything, because a zero-logic action has no branches to miss; the coverage report (/verify) is the check. If an action can't clear the thresholds from a single exercising call, give it its own test instead of skipping coverage.

6. UI rules

If the feature has visual components, apply /ui skill guidelines (design-system, components, patterns references).

Feedback:

• No console.log(err) in catch blocks — the axios interceptor handles snackbar display
• Use catch { /* interceptor handles */ } or re-throw

Destructive actions — confirmation proportional to impact:

• Low impact (remove member): simple confirm dialog
• High impact (delete org/account): type-to-confirm with entity name

Consistency (see /ui patterns):

• Dialogs: max-width="440"
• Destructive buttons: color="error" + variant="tonal" (inline) or variant="flat" (in dialog)
• Primary buttons: color="primary" + variant="flat" + class="text-none text-body-medium"
• All buttons: :class="config.vuetify.theme.rounded"
• Role chips: roleColor() + variant="tonal" + size="small" + class="text-capitalize"

Responsive:

• Side-by-side layouts: flex-column flex-sm-row
• Data tables: hide non-essential columns on smAndDown
• Form buttons: :block="$vuetify.display.xs" or flex-wrap

State & UX guards:

• Forms with dirty flag → beforeRouteLeave guard
• Dismissible banners → persist in sessionStorage, not component data
• Active context → visually indicate (badge, border, chip)
• Generated links/tokens → copy button with clipboard API
• Dates: relative for recent ("2d ago"), absolute for historical ("DD/MM/YY")

Phase 2 — Definition of Done

7. Self-review checklist

Flow completeness:

• Every API has a UI, every action shows feedback
• Destructive actions have appropriate confirmation
• Edge cases handled (last-one, retry, no mailer)

Consistency:

• Dialog widths, button styles, chips follow rules above
• Responsive layout verified at mobile breakpoint

State:

• Unsaved changes guarded
• Dismissible UI persisted correctly
• Active context visually marked

Modularity:

• Isolated in ONE module (or justified)
• No cross-module Store imports except useAuthStore/useCoreStore
• Tests added
• Tests: unit tests (*.unit.tests.js) for all changes, except a pass-through store action (see Phase 1 §5) which only needs to be exercised once in the module's store test. E2E (*.e2e.tests.js) only if the change affects a critical user flow (auth, org onboarding, invite/join).

Error documentation:

• If a non-obvious bug was fixed, document it in ERRORS.md (root of repo) with: symptom, root cause, fix

7b. Elegance check

For non-trivial changes: pause and ask yourself "is there a simpler or more elegant approach?" If the current implementation feels hacky, refactor before proceeding.

8. Run /verify

9. Run /pull-request