Nova feature

Translation note: Originally authored in Portuguese (pt-BR) by Igor Uehara (igoruehara/spec-driven, MIT). Translated to English by this hub to keep the repository language consistent. Original content unchanged in meaning; see the upstream repo for the pt-BR source.

Skill: New feature (SDD loop)

Opens and drives a feature through the pipeline of README.md. The spec is the contract; fill it in in the order of the gates and stop at each one for review. Follow the conventions of CLAUDE.md.

Principles

• Ask in short batches with AskUserQuestion; offer "(Recommended)" defaults. But when the ambiguity is deep and branched (one decision depends on another), replace the batch with a grilling session — run /clarificar (one question at a time, walking the tree) and come back with the understanding closed. Especially useful at the design and spec gates.
• Do not delegate spec.md — the acceptance criteria are the contract; the user validates them.
• Outward-facing actions (create issue, publish) → confirm first.
• Tools-aware: only use an MCP if it is available in the session (mcp__<server>__*); otherwise, proceed without it and record it as a pending item.
• Connection lock: an active MCP does not authorize use. Confirm which account/workspace the connection points to before reading the story, and reconfirm before creating issues (writing to the wrong account — e.g.: personal vs project Jira — leaks data). Use the connection validated in /kickoff if there is one.

Phase 1 — Feature identity

1. Compute the next number: highest NNNN in specs/ + 1, with 4 digits (e.g.: 0002).
2. Ask for a short kebab-case name → folder specs/NNNN-<nome>/.
3. (tools-aware) Import context: if Jira/Linear is connected, ask whether the feature has a story/epic. If yes, read the issue and use it to seed product.md; store the key in the frontmatter (jira: PROJ-123). If Confluence/Notion is connected, pull related pages. If no management/doc tool is connected and the user wants to pull inputs, offer to run /integracoes now (neutral — let them say what they use); if they decline, proceed without it and record the pending item.

Phase 2 — Decide the tier

Ask (gate): "does this introduce a hard-to-reverse decision or a new domain frontier?"

Answer	Tier	Artifacts to create
No, it's trivial (≤3 files)	Trivial	just the PR — or specs/quick/NNN-slug/ (TASK.md + SUMMARY.md) to leave a trail.
No, but it's an isolated feature	Small	spec.md + tasks.md
Yes	Architectural	product.md + design.md + domain.md + spec.md + tasks.md

When in doubt, promote the tier (it's cheap). Copy the templates from specs/_templates/ into the folder.

Phase 3 — Fill top-down (through the gates)

For each artifact of the tier, draft from the template and stop at the gate for review:

1. product.md (architectural) — problem, for whom, metric, goals/non-goals.
2. design.md (architectural) — solution + the 5 axes (stack, architecture, infra, quality, observability) + alternatives/trade-offs/risks. Hard-to-reverse decision → becomes an ADR. Entangled trade-offs? Run /clarificar to grill the branches before fixing the decision. If a domain-modeler/spec-reviewer subagent exists, offer to delegate to them.
3. domain.md (architectural) — bounded context, ubiquitous language, aggregates, events. Update docs/glossary.md and docs/architecture/context-map.md if terms/boundaries emerge.
4. spec.md (always) — acceptance criteria in Given/When/Then, edge cases, out of scope. Gate Definition of Ready: is each AC testable and unambiguous? Any AC still vague or a "how should it behave when…" left open? Run /clarificar to close the tree before writing it down. If there is a spec-reviewer, use it. Rule combining several factors (flags, states, modes)? Use the Decision Matrix from the template — a truth table is denser and cheaper in tokens than prose, and each row becomes a test.
5. tasks.md (always) — break down into tasks, each mapping to one or more ACs + a test plan.

Phase 4 — Task breakdown and tracking

1. Fill in the tasks.md table (task → covers AC → depends on → status).
2. (tools-aware) Create issues: if Jira/Linear is connected, offer to create one issue/subtask per task (confirm first). Writing is one way (repo → tool); record the task # ↔ issue key mapping in tasks.md. If there is no management MCP, offer to run /integracoes to connect now; if the user declines, leave the column to fill in by hand.

Phase 5 — Ready to implement

• Check the Definition of Ready (see README.md): testable ACs, non-goals, terms in the glossary, and — at the architectural tier — design.md approved.
• Summarize with clickable links and point to: implement respecting the layering rule (src/README.md), one test per AC. Remind about the Definition of Done for the merge (green ACs, ADRs, live docs, faithful spec).
• If it is a git repository and the user wants to, offer a commit of the spec artifacts.

Phase 6 — Validation (UAT)

After implementation (possibly in another session), run the /validar skill: it runs the gates of docs/engineering/TESTING.md, maps AC-N → test, resolves SPEC_DEVIATION, checks the Definition of Done, and updates docs/STATE.md. Close with /handoff if you are pausing.