ratatoskr/docs/methodology.md

Methodology

The Corviduo preferred development pipeline for non-trivial work:

(optional) Vor → (required) Contract → branch (direct or AFK TDD) → verify against contract → merge/commit

Each step front-loads work into the cheapest place to do it:

• Vor front-loads ambiguity-resolution so the contract is sharp.
• Contract front-loads design so implementation is mechanical.
• TDD binds the contract to executable verification, vertical slice first.
• Audit closes the loop: code is checked against the spec, not the spec against the code.
• Commit lands the artifact + the supporting record together.

The contract is the load-bearing artifact in every path. Vor sharpens it; TDD executes against it; the audit verifies against it; the commit ships it.

---

1. Vor (optional)

When the ask carries ambiguity, run /vor <ask> before drafting the contract. Vor routes through the Vor UI sidecar and produces a structured response file: assumptions, questions with recommendations, devil's-advocate pushback.

The /vor skill carries a built-in fuzziness gate that helps decide whether to invoke. Unambiguous asks (concrete verb + noun + scope) skip Vor and go straight to the contract.

A contract whose ambiguity was resolved via Vor is Vor-graduated: vor_graduated: true in frontmatter. Sleipnir's INV-032 reads this flag at intake and skips the plan-converge phase in AFK dispatch, since the design questions are already resolved.

2. Contract (required)

Before any non-trivial implementation. The contract is the source of truth that code is written to satisfy — not documentation of existing code.

• Format spec: docs/contracts/CONTRACT-FORMAT.md (v2.1 current).
• Module contracts: docs/contracts/<module>.contract.md.
• Issue-scoped contracts: docs/contracts/issues/<N>.contract.md, which additionally require a populated prd: block pinning the issue body
  • lock-in comment SHA hashes.

Function blocks carry FN / BRIEF / PRE / POST / ERRORS / STATE / STEPS / TESTS. The TESTS section is the load-bearing artifact for step 3 — TDD reads from there.

Skip the contract for: bug fixes that don't change signatures or behavior, trivial helpers, config changes, doc-only changes (per CLAUDE.md § Contract-first workflow).

3. Branch — direct or AFK TDD

From the contract, two execution paths. Both run red-green-refactor against the contract's TESTS section per the tdd skill's vertical-slice discipline — tracer bullet first, then incremental loop. Never write all tests then all code (produces tests of imagined behavior).

Direct TDD

The developer writes the code RGR locally.

AFK TDD (sleipnir-shaped)

For issue-scoped work, AFK dispatch via Sleipnir:

1. /sleipnir-preflight <N> validates the contract's prd: pin via scripts/contract_drift_check.py, posts the canonical agent preamble as a Gitea comment + pins it to the contract, then applies the ready-for-agent label via tea.
2. Sleipnir's daemon picks up the labelled issue, spawns an agent into a per-issue git worktree, drives plan → implement → review → fixup → merge → done → corpus.
3. Vor-graduated contracts skip the plan-converge phase per INV-032.

Pre-dispatch policy is hard: see CLAUDE.md § Issue → AFK dispatch hygiene.

4. Verify against contract

The audit pass. CONTRACT-FORMAT.md § 6 (Audit protocol) defines the nine-point structured verification:

1. Signature match
2. PRE enforcement
3. POST satisfaction
4. Step coverage
5. Error handling
6. Invariant preservation
7. Test coverage
8. Resume correctness
9. No extra behavior

• Direct path: the developer audits their own work, or a sibling pass (codex-via-Volva, peer-review-via-althing) performs the audit.
• AFK path: Sleipnir's review phase invokes the audit automatically; verdict gates fixup/merge.

5. Merge / commit

Audit-clean work merges to the project's main branch. Per CLAUDE.md § Persistent-memory + housekeeping commit-along rule, persistent-memory.md rides with the merge if dirty. Same for any housekeeping files where they exist (HANDOFF-SUMMARY.md, NEXT-STEPS.md, README.md, State-Of-Development.md).

Atomic commits: one logical change per commit; new code + new tests + doc updates ride together where they form a coherent unit. No backwards-compat shims, deprecation periods, or rename aliases until v1.x — when something is redesigned, the old code is deleted and all references are updated in the same commit.

---

What this file is, and isn't

This file describes the pipeline. Each step delegates to the canonical that owns its mechanics:

Step	Owned by
Vor	/vor skill (lives in Galdrabok)
Contract format	docs/contracts/CONTRACT-FORMAT.md
TDD discipline	tdd skill
Sleipnir AFK	/sleipnir-preflight, /sleipnir-scaffold skills + Sleipnir daemon
Audit	CONTRACT-FORMAT.md § 6
Commit hygiene	PRACTICES.md (slated to migrate from Galdrabok); CLAUDE.md § Persistent-memory commit-along
Principles	PRINCIPLES.md (what to optimize for across all of the above)

This file is canonical at corviduo-project-template/docs/methodology.md and pinned via .corviduo-canonicals.toml. When a derivative Corviduo project seeds from the template, this file copies in alongside the rest and is kept in sync by scripts/canonical_sync.py / scripts/canonical_drift.py.