Project Context

• CLAUDE.md: !find . -maxdepth 1 -name "CLAUDE.md" -type f
• project-discovery.md: !find . -maxdepth 3 -name "project-discovery.md" -type f

Operating Principles

• Interview relentlessly, but explore first. If a question can be answered by reading the codebase, project docs, coding standards, ADRs, or existing feature specs — or by querying a read-only tool already available to this session that authoritatively answers it (for example a connected schema or data-source tool) — explore instead of asking. Only surface questions that genuinely require the user's judgment. The connected-tool path is gated on availability, not on a fresh judgment: use it only when such a read-only tool is actually permitted to this skill; if none is available, ask the user as today (see Step 4).
• Walk the design tree. Decisions have dependencies. Resolve foundational decisions first (what the feature does, who uses it, what outcome it produces). Then descend into dependent decisions (flow, states, edge cases, coordination points). Never ask a dependent question before its parent is settled.
• Recommend, then ask. For every question surfaced to the user, provide a recommended answer with rationale grounded in evidence (code, docs, conventions, or stated goals). The user can accept, redirect, or provide a nuanced response.
• Behavior, not implementation, in the spec. The specification captures WHAT the feature does, for WHOM, and WHY — at a level a reader who has never opened the codebase can understand. Language primitives, file/line references, function or class names, library mechanics, implementation patterns, and internal env/flag names DO NOT appear in feature-specification.md. Product-level subsystem names ("events processing system", "backend service"), user-facing UI vocabulary (popover, modal, toast), URL paths, behavioral verbs, and user-observable states DO. Technology brand names generalize one level up (NATS → "events processing system"; PostgreSQL → "database"; Redis → "cache"). This rule is language-agnostic — it applies equally to Go, Rails, Node, Python, Swift, Kotlin, and frontend JavaScript code. Any examples given in references or templates are illustrative, not an exhaustive deny-list.
• Load-bearing mechanics go in feature-technical-notes.md, not the spec. When a mechanic is load-bearing for a behavior — meaning the behavioral commitment in the spec is only correct because of that mechanic (ordering, durability, consistency, visibility timing) — the behavioral consequence goes in the spec sentence, and the mechanic goes in a T# note linked inline from that sentence. The tech-notes file is LAZILY created — it exists only when at least one load-bearing mechanic qualified. Mechanics that are discoverable from the code repo (an existing pattern, an in-use library, a documented convention) do NOT belong in the tech-notes file either — plan-implementation will find them from the code. Mechanics that do not affect observable behavior are pure implementation and belong in the implementation plan, not here.
• YAGNI is a first-class operating principle. Apply the evidence-based YAGNI rule defined in ../../references/yagni-rule.md. Every behavior, alternate flow, edge case, coordination, open item, or other commitment in feature-specification.md must cite at least one piece of evidence per the rule's evidence test (user-described need, named direct dependency, existing production code path that breaks, applicable regulation, documented incident or measured metric). When evidence justifies the item, apply the simpler-version test — replace with the strictly simpler version that satisfies the same evidence. Items that fail the evidence test get demoted to a ## Deferred (YAGNI) section in the spec with the trigger that would justify reopening, never silently dropped and never silently kept. Every spec section is ongoing maintenance and a pattern future agents will copy.
• Evidence quality is a companion operating principle. Apply the evidence rule from ../../references/evidence-rule.md alongside YAGNI. YAGNI gates inclusion (is there any evidence?); the evidence rule characterizes the quality of the evidence each spec commitment rests on. Name the trust class of cited sources (codebase, web, provided); mark single-source web claims that drive a commitment; label commitments with no evidence at any tier as a distinct deferred state rather than weak evidence. The proximity-to-origin principle is a heuristic, not a strict tier list.
• All sub-agents in this skill run on sonnet. When launching any Agent tool call in this skill, pass model: "sonnet".

Plan a Feature

Step 1: Capture the Feature Request and Output Location

Read the user's argument and conversation context to extract the feature being planned. If the request is too thin to start (e.g., just "plan a feature"), ask the user for a one-to-two-sentence description of what the feature does and what outcome it produces — nothing else yet.

Resolve the output location:

• If the user specified a folder path, use it.
• Otherwise, propose a folder name of 3 to 5 words in kebab-case (e.g., docs/features/user-invite-flow/, docs/plans/bulk-export-jobs/). Prefer placing it under an existing documentation root discovered via CLAUDE.md's ## Project Discovery section, project-discovery.md, or Glob fallbacks (docs/features/, docs/plans/, docs/).
• Confirm the folder name with the user before creating files. If the folder does not exist, create it.

Up to four files will be written. The primary spec lives at the root of {folder}/; the companion artifacts live in {folder}/artifacts/ to keep the planning folder uncluttered:

• {folder}/feature-specification.md — the primary behavioral spec. Always written.
• {folder}/artifacts/decision-log.md — the full decision history with rationale, evidence, and rejected alternatives. Always written.
• {folder}/artifacts/team-findings.md — review-team findings and how each was resolved. Always written.
• {folder}/artifacts/feature-technical-notes.md — load-bearing mechanics that were captured because they were needed to correctly specify a behavior. Lazily created — written only if at least one T# qualifies during the interview (Step 4) or finding resolution (Step 7). If no T# qualifies, the file is never created and the spec contains no T# links.

Create the artifacts/ subfolder before writing the companion files if it does not already exist.

The files cross-reference each other. The main spec cites decisions with inline parenthetical links like ([D4](artifacts/decision-log.md#d4-invite-expiration-window)) and cites technical notes (when the file exists) with inline parenthetical links like ([T3](artifacts/feature-technical-notes.md#t3-ack-ordering)). The decision log, findings log, and tech-notes file (all siblings inside artifacts/) cross-link through Driven by findings: / Linked technical notes: / Affected decisions: / Affected tech-notes: / Supports decisions: fields, and all reference back into the spec with ../feature-specification.md paths.

Step 2: Discover Before Asking

Before asking the user anything beyond the initial framing, explore the codebase and project documentation to gather context that will answer as many design-tree questions as possible. Use Glob and Grep to find:

• CLAUDE.md, AGENTS.md, and any project-discovery.md — tech stack, constraints, conventions.
• ADRs in docs/adr/ or docs/architecture/decisions/ — prior architectural decisions the feature must respect.
• Coding standards in docs/coding-standards/ or .github/CODING_STANDARDS.md — rules the feature's design must align with.
• Existing feature specifications or PRDs — tone, structure, level of detail the team expects.
• Code adjacent to what the feature touches — current behaviors, p