Skip to main content

Ratiba methodology

Ratiba follows the S4U Development Methodology (single source: /Users/soft4u/Development/s4u-methodology/docs/methodology.md). This section captures Ratiba-specific overrides and supplements where the agentic-product context introduces failure modes the deterministic-codebase methodology doesn't fully address.

What's already wired in the repo​

  • CLAUDE.md — project-specific instructions, ADR table, tech stack, port assignments.
  • AGENTS.md — symlink to CLAUDE.md (Linux Foundation cross-tool standard).
  • .claude/settings.json — Stop hook + plugin enablement (superpowers, code-review, code-simplifier, typescript-lsp, serena, context7, aikido, coderabbit).
  • .claude/hooks/ — three layers of defence (lint-edited.sh, pre-push-gate.sh, stop-verify.sh).
  • .claude/agents/ — four reviewer subagents (api, security, compliance, migration).
  • scripts/check-adr.sh — refuses to commit if a numbered ADR isn't registered in CLAUDE.md.
  • scripts/check-docs-sync.sh — refuses to commit if backend files are unmapped in architecture-index.json or their mapped page is more than 30 days stale.

Non-negotiable rules every session​

  1. Design before code — brainstorm → spec → plan → execute. Specs go to docs/superpowers/specs/; plans to docs/superpowers/plans/.
  2. Quality gates before every commit — Ruff F-codes (zero), tsc --noEmit (zero), tests for modified production code.
  3. No mocking by default — testcontainers for external services; mocks need an inline approval comment with reason + reviewer + date.
  4. Test evidence required — paste actual pytest output in responses, not "tests pass."
  5. ADRs before architectural decisions — numbered, registered in CLAUDE.md table, in docs/adr/ADR-NNNN-*.md.
  6. Subagent-driven development for multi-step tasks — fresh subagent per task, two-stage review (spec compliance, then code quality).
  7. Direct-to-master is fine — quality gates make feature branches optional.
  8. No native dialogs — inline confirmation + toast notifications.

Coming with Phase B research​

The agentic-development methodology supplement (agentic-development.md) is gated on Phase B of the agentic research investment. It will cover:

  • Subagent-driven development for non-deterministic artifacts.
  • Prompt versioning and regression strategy.
  • Eval-driven development as the new test pyramid.
  • Auto-debuggable logging conventions (so an AI can diagnose production issues from logs alone).
  • Patterns lifted from the sister projects (zol-rag, trust-relay-workflow) for AI-debug logging, prompt registries, observability.