Spec To Implementation

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.”

Converted and distributed by TomeVault — claim your Tome and manage your conversions.