Skill: spec-to-implementation

Purpose

Implement Solidity function(s) or modules directly from an inline comment-level specification, following a deliberate implementation-first workflow.

This skill exists to translate intent into code while:

• completing and updating NatSpec created during scaffolding
• preserving correctness
• surfacing assumptions explicitly
• remaining audit-ready

Completeness and optimization are secondary to faithful implementation.

When to Invoke

• A contract has already been scaffolded
• Inline comments describe intended behavior or invariants
• The logic is conceptually understood but not yet encoded in Solidity
• You want a stable implementation baseline before:

- test generation - refactoring - gas optimization

Inputs Required

• Target contract(s) and function signature(s)
• Inline comment-level spec (bullet points preferred)
• Explicit assumptions about:

- token behavior (ERC20 quirks, hooks, rebasing) - oracle usage (freshness, decimals, trust) - access control (roles, admin powers) - upgradeability (storage layout constraints, ABI stability)

If assumptions are missing or ambiguous, they must be surfaced explicitly.

Actions

1) Translate the spec into implementation intent

• Restate the inline spec in concrete implementation terms:

- inputs to outputs - state before to state after

• Identify:

- state transitions - external calls and dependencies - accounting paths and units (assets, shares, debt, rewards)

2) Design the control flow explicitly

Before writing code, reason about:

• call ordering (effects before interactions)
• failure modes and revert conditions
• edge cases (zero values, rounding, max or min bounds)

3) Implement the Solidity code

Implementation must:

• follow the specification literally
• use clear, explicit control flow
• reuse shared logic from src/utils or protocol-specific lib/ folders where applicable
• isolate accounting logic into readable, reviewable sections
• prefer readability and correctness over micro-optimizations

4) Update and finalize NatSpec documentation

NatSpec added during the scaffolding phase must now be completed and corrected.

For every public or external function:

• replace placeholder NatSpec with accurate descriptions
• document:

- behavior - parameters and return values - state changes - external calls - assumptions and trust boundaries - known edge cases and risks

NatSpec must explain why decisions were made, not restate the code.

5) Remove inline comment-level specification

After implementation is completed and explicitly confirmed by the user or Codex developer:

• Delete all inline comment-level specification used only for guidance
• Do not remove:

- finalized NatSpec - explanatory comments that justify design decisions

• Inline specs must not persist once behavior is locked

Rationale: inline specs are transitional scaffolding. Persisting them risks
divergence between comments and behavior and confuses audits.

Constraints and Safety Rules

• Must not write or modify tests

(tests are generated via implementation-to-tests)

• Must comply with all rules in .codex/constraints/solidity-style.md
• State updates must precede external calls
• Custom errors must be used instead of revert strings
• ERC20 non-compliance must be assumed
• Accounting logic must be:

- clearly isolated - commented - unit-consistent

• No gas optimizations that obscure correctness or intent
• No changes to unrelated code or public APIs unless explicitly requested

Outputs

• Modified Solidity source files implementing the specified behavior
• Updated NatSpec documentation reflecting final behavior
• Inline comment-level specs removed after confirmation

Verification

• Code compiles cleanly with forge build
• Formatting passes forge fmt
• NatSpec accurately reflects implemented behavior
• Inline comment-level specs are removed after confirmation
• Any ambiguity or missing spec detail is explicitly documented for follow-up

Handoff

After successful execution, this skill should be followed by:

• implementation-to-tests to lock behavior

Example Prompts

• “Use spec-to-implementation to implement claimRewards(address to),

update NatSpec, then remove the inline spec once confirmed.”

• “Translate this ERC4626 withdrawal spec into an implementation and

remove inline comments after final review.”