New Feature

---
name: New Feature
description: End-to-end workflow for scoping, proposing, reviewing, and implementing a new feature using OpenSpec and TDD.
category: Development
tags: [feature, openspec, tdd, workflow]
args: feature_request
---

You are a scientific programmer that values testing, code quality, reproducibility, metadata preservation, traceability, interpretability, and performance. You are starting a new feature workflow. The user's feature request is: $ARGUMENTS

**Guardrails**

- Do NOT write any implementation code until the proposal is approved.
- Follow OpenSpec conventions strictly (see `openspec/AGENTS.md`).
- Use TDD when implementing (tests before implementation code).
- Always ask clarifying questions before proceeding if anything is vague, ambiguous, or underspecified. Do not assume.

**Steps**

1. **Ensure feature branch**: Check if you are on a feature branch (not `main`). If on `main`, ask the user what branch name to create (suggest one based on the feature), then create and switch to it before proceeding.

2. **Understand scope**: Use subagents to explore the codebase and understand the current state relevant to this feature. Investigate:
   - Existing trait modules in `sleap_roots/` (lengths, angles, tips, bases, etc.)
   - Pipeline classes and the networkx trait dependency graph in `sleap_roots/trait_pipelines.py`
   - Test fixtures in `tests/fixtures/` and test data in `tests/data/`
   - Related specs in `openspec/specs/`
   - Active changes in `openspec/changes/`

3. **Ask clarifying questions**: Based on what you learned from the codebase exploration, ask the user any clarifying questions about:
   - Requirements and expected behavior
   - Edge cases (empty arrays, NaN, single points)
   - Biological validity and scientific accuracy
   - Data handling and coordinate systems
   - Impact on published results or reproducibility
   - Memory considerations for large datasets
   - Which plant types are affected (dicot, monocot, etc.)
   - Which test data in `tests/data/` is relevant
   Do not proceed until you have clear answers.

4. **Create OpenSpec proposal**: Run `/openspec:proposal` to scaffold the change proposal, following all OpenSpec best practices. Ground the proposal in what you learned from steps 2-3. The proposal's `tasks.md` must explicitly outline a TDD approach: for each task, specify what tests will be written first and what behavior they verify before implementation begins.

5. **Review the proposal**: Run `/review-openspec` to have the proposal critically reviewed by 5 specialized subagents. If the review verdict is BLOCKED, fix the issues raised and re-run the review. Repeat until the verdict is APPROVED or NEEDS REVISION.

6. **Reconcile every blocking finding before user approval**: For each BLOCKING and IMPORTANT finding from the review, produce an explicit reconciliation entry containing:
   - The finding quoted verbatim — especially any specific technical mechanism named by the reviewer (e.g., "round-trip through a synthetic `.slp` file", "use `sio.load_slp`", "open the TIFF backend to read metadata")
   - How the finding is addressed in the revised proposal
   - The exact line in the proposal where the reviewer's specified mechanism now appears

   **Critical**: Take reviewer language literally. If a reviewer specified "round-trip through a synthetic .slp file", do not substitute "construct Labels in memory and pass them through the pipeline" — those are not equivalent. Past sessions have silently swapped reviewer-specified mechanisms for convenient approximations, only for the same issue to be flagged later by GitHub Copilot.

   If a finding is genuinely unaddressable in this proposal, defer it with a written justification and (if appropriate) file a follow-up GitHub issue. Do NOT proceed to user approval until every BLOCKING finding has a concrete reconciliation.

7. **Get user approval**: Present the reviewed proposal and the reconciliation entries from step 6 to the user. Wait for explicit approval before proceeding to implementation.

8. **Implement with TDD**: Once approved, run `/openspec:apply` to implement the change using test-driven development. Write tests before implementation code.

9. **Reconcile implementation with proposal before committing**: After implementation but BEFORE running `/pre-merge-check` or creating a commit, re-read the approved `proposal.md`, `spec.md`, and `tasks.md`. For every described behavior, data structure, and mechanism, verify the actual implementation matches. In particular:
   - If the spec says "6-node skeleton", verify the test/fixture uses 6 nodes
   - If the spec says "round-trip through `.slp`", verify the test actually calls `sio.save_slp` and `sio.load_slp` (or `Series.load` with a real file)
   - If the proposal names specific functions/APIs, verify those exact functions/APIs are used

   If the implementation had to deviate from the approved proposal (e.g., because a bug was discovered during implementation, a library constraint was hit, or a reviewer's assumption was wrong), you MUST update `proposal.md`, `spec.md`, and `tasks.md` to reflect reality, including a short `### Why N instead of M?` section explaining the deviation. Silent drift between the approved proposal and the committed implementation is NOT acceptable.

   If a bug was discovered during implementation that required a workaround, file a new GitHub issue for it before committing and reference the issue in the updated proposal.

10. **Proceed to pre-merge**: Run `/pre-merge-check` to complete the verification and PR workflow.