spec

name	spec
description	Interview the requester about a proposed change to the Hipo contracts, then write a short spec to docs/specs/ and get sign-off before any implementation. Use whenever a new feature, behavior change, or protocol tweak is requested, before writing code.

Spec: interview before implementing

These contracts hold user funds on mainnet. Before implementing any feature or behavior change, produce a small written spec and get it approved. Do not start coding, and do not modify contracts, wrappers, or tests, until the requester approves the spec.

Step 1 — Understand the idea

Read the request, then read the relevant parts of docs/architecture.md, the affected contracts, and the matching graphs/*.dot flow before asking anything — questions should build on that context, not rediscover it.

Step 2 — Interview

Ask focused questions (use AskUserQuestion when options are enumerable, free-form otherwise), in as many rounds as needed but only about things that change the design. Cover whichever of these apply:

• Goal: what user-visible problem is being solved? How is it observed today?
• Scope: which contracts and flows change? What is explicitly out of scope?
• Protocol invariants: does the change interact with the exchange-rate identity, the participation state machine, the deposit/unstake fairness rules, or loan safety? Which invariant statements in docs/architecture.md must still hold?
• Compatibility: does stored contract data change layout (treasury save_data / extension, wallet, participation)? Does the deployed mainnet state need a migration in the upgrade path? Do message schemas change (update contracts/schema.tlb, docs/integration.md, and external integrators)?
• Economics and gas: effect on fees, rewards split, or worst-case gas (MaxGas/MinGas bounds and the fee constants in contracts/imports/)?
• Rollout: pure code change vs. governance action vs. treasury/parent/wallet upgrade? Any ordering constraints with the running rounds?
• Testing: which specs cover it; what new cases prove the change and its edge cases?

Step 3 — Write the spec

Write docs/specs/YYYY-MM-DD-<slug>.md with these sections, kept short and concrete:

# <Title>

## Problem
## Decision
## Changes            <!-- per contract/file, in one or two lines each -->
## Invariants         <!-- what must remain true, and why this change preserves it -->
## Compatibility      <!-- data layout, message schemas, upgrade/migration plan -->
## Test plan
## Out of scope

Record what was decided and why, including rejected alternatives when the choice was not obvious — the spec is the durable memory of the interview.

Step 4 — Sign-off, then implement

Present the spec, ask for approval, and apply requested revisions to the spec file first. Only after approval, implement exactly what the spec says; if implementation reveals the spec was wrong, stop and update the spec (and confirm) before continuing. Update docs/architecture.md, docs/integration.md, and the graphs/ diagrams whenever the change makes them stale.