feature

name	feature
description	Start or resume feature development workflow -- restores context, creates feature doc, creates task plan, implements contracts, updates feature docs
argument-hint	<feature-name>

Feature Development Workflow

Working on feature: $ARGUMENTS

Execution Order

1. Read research -- Read all files in research/$ARGUMENTS/ if they exist
2. Create feature doc -- Write feature-docs/$ARGUMENTS.md by synthesising the research docs (see below)
3. Create task plan -- Write .task_plan.md -- primarily informed by the feature doc; may also reference research docs directly for additional detail
4. Implement -- Write contracts and interfaces following Solidity style rules (see .claude/rules/solidity-style.md)
5. Update feature doc -- Ongoing throughout implementation: log progress, decisions made, and any design changes
6. Tests -- Only when explicitly asked

If feature-docs/$ARGUMENTS.md already exists, read it first to restore context, then continue from where work left off.

---

Feature Doc (feature-docs/$ARGUMENTS.md)

The feature doc is the single source of truth for the feature. Create it before the task plan by synthesising the research docs. Keep it short and concise — capture only what is essential, not a full rewrite of the research.

It should capture:

• What needs to be done -- scope and goal of the feature
• Where to make changes -- which contracts, interfaces, and files are involved
• How to make changes -- implementation approach; if the research doc prescribes a specific approach follow it, otherwise use a subagent to analyse the codebase and determine the best approach before writing this section
• Key design decisions and why they were made
• Trade-offs and gotchas -- anything worth watching out for

During implementation, keep this doc updated with actual progress and any decisions that deviate from the original plan. All design decisions go here — if something changes, update this doc. Research docs are input only: used once to create the initial feature doc and never updated after that.

---

Task Planning (.task_plan.md)

Always create .task_plan.md at the project root before starting implementation. This file:

• Contains the execution plan with phases and checklist
• Tracks progress, errors, and current status
• Is not tracked by git -- purely a working file
• Persists across sessions for the same feature -- append, don't overwrite

---

Research (research/)

Research docs in research/$ARGUMENTS/ feed the initial feature doc and are not touched after that. They can be generated by Claude during a research phase or pasted in directly by the user. They may contain:

• Design docs -- architecture, interface design, flow diagrams
• Implementation docs -- step-by-step implementation details
• Reference material -- relevant protocol docs, external references
• Analysis -- security considerations, gas analysis, comparisons

Important: Research docs (especially implementation docs) may contain code snippets -- treat these as pseudo-code for inspiration only, NOT as source of truth. Always write correct, bug-free logic yourself. If you see a better approach than what is described, always present it to the user -- explain what it is and why it is better -- and ask whether to use it instead.

---

File Structure

New oracle contracts follow this layout:

contracts/
  ├── interfaces/IMyOracle.sol     # Interface first
  └── oracles/MyOracle.sol         # Implementation

test/
  └── MyOracle.ts                  # Unit tests (only when asked)

deploy/
  └── NN-deploy-my-oracle.ts       # Hardhat-deploy script

feature-docs/
  └── $ARGUMENTS.md                # Feature doc (git-tracked)

research/
  └── $ARGUMENTS/                  # Research input (NOT git-tracked)

---

Subagent Strategy

During active development, if asked something mid-work (explain code, find usages, compare approaches), use a subagent to handle it. This keeps the main context window clean — delegate the exploration, return only the answer.

---

Operational Rules

1. Ask freely -- If anything is unclear or ambiguous, ask the user before proceeding. Never assume.
2. Read before decide -- Before major decisions, re-read the feature doc and plan file.
3. No landmines -- Find root causes, no temporary fixes. Leave no hidden hazards in the code.
4. 2-Action Rule -- After every 2 search/browse operations, IMMEDIATELY save key findings to files.
5. Update after act -- After completing any phase: mark status, log errors, note files modified.
6. Log ALL errors -- Every error goes in the plan file.
7. Never repeat failures -- if action_failed: next_action != same_action. Track attempts, mutate approach.
8. 3-Strike Protocol -- After 3 failed attempts at the same problem, escalate to user.