Oodle / Workshop materialBack to workshop hub
Programme

Starter: code-vs-logic audit

Pre-filled contract for the retrospective code-versus-business-logic audit.

Starter contract: retrospective code-vs-business-logic audit (backlog #15)

Pre-filled from templates/requirement.md. Richard's headline idea: audit the decision-engine code against the business documents that describe the current logic. One-off audit, not a per-PR gate.

On the board: this is OODLE-202 on the mock Jira board. Best Wave-1 opening: connect the oodle-jira MCP and say "grab OODLE-202 and grill me". Then compare what you froze against this contract.

WHO

  • User: a DS/engineering pair on the decision engine (+ a PM sanity-checking findings).
  • Situation: a codebase too large to hold in your head; business-logic docs live in Confluence; nobody reviews code retrospectively against them.
  • Task they are trying to complete: find where code and documented logic disagree, with evidence.

WHAT

  • Required behaviour (not implementation): for [one scoped rule area: pick 1–3 documented rules, not the whole engine], locate the implementing code and classify each rule as ALIGNED / MISMATCH / NOT FOUND, with file:line references and the doc passage quoted.
  • Input: the decision-engine repo (read-only) + the approved business-logic doc(s) via the Atlassian MCP or exported copies.
  • Output: a findings report with one entry per rule (verdict, doc quote, code reference, one-line explanation), plus a draft realignment ticket per MISMATCH.

WHY

  • Intent: keep the mapping between business logic and code under control ("the elephant in the dark room").
  • Business outcome: mismatches surface as tickets instead of production surprises; the FCA-explainability story gets stronger.
  • Evidence/source: Richard's interview; backlog #15.

NOT

  • Explicit exclusions: no code changes, the audit is read-only; no writes to Jira/Confluence without human approval of each ticket.
  • Protected areas: the scored decision path is FCA territory. The audit reads it and proposes changes only as tickets for human review.
  • Agent must never: assert a mismatch without quoting both the doc passage and the code location.

DONE

  • Acceptance signals that pass or fail: every finding independently checkable (a human clicks the file:line and the doc link and sees what the report claims); at least one finding demoed end-to-end; zero unsourced claims.
  • Authoritative verifier: human spot-check of ≥2 findings against source.

Scenarios

Scenario: happy path
  Given a documented rule with a clear implementation
  When the audit runs
  Then the report marks it ALIGNED with doc quote and file:line reference

Scenario: edge case
  Given a documented rule the audit cannot locate in code
  When the audit runs
  Then the report marks it NOT FOUND and says where it looked

Scenario: explicit exclusion
  Given a mismatch on the scored decision path
  When the audit proposes realignment
  Then it drafts a ticket for human review and changes nothing itself
Original Markdown
# Starter contract: retrospective code-vs-business-logic audit (backlog #15)

Pre-filled from `templates/requirement.md`. Richard's headline idea: audit the decision-engine code against the business documents that describe the current logic. **One-off audit, not a per-PR gate.**

> **On the board:** this is **OODLE-202** on the mock Jira board. Best Wave-1 opening: connect the `oodle-jira` MCP and say *"grab OODLE-202 and grill me"*. Then compare what you froze against this contract.

## WHO

- User: a DS/engineering pair on the decision engine (+ a PM sanity-checking findings).
- Situation: a codebase too large to hold in your head; business-logic docs live in Confluence; nobody reviews code *retrospectively* against them.
- Task they are trying to complete: find where code and documented logic disagree, with evidence.

## WHAT

- Required behaviour (not implementation): for `[one scoped rule area: pick 1–3 documented rules, not the whole engine]`, locate the implementing code and classify each rule as ALIGNED / MISMATCH / NOT FOUND, with file:line references and the doc passage quoted.
- Input: the decision-engine repo (read-only) + the approved business-logic doc(s) via the Atlassian MCP or exported copies.
- Output: a findings report with one entry per rule (verdict, doc quote, code reference, one-line explanation), plus a draft realignment ticket per MISMATCH.

## WHY

- Intent: keep the mapping between business logic and code under control ("the elephant in the dark room").
- Business outcome: mismatches surface as tickets instead of production surprises; the FCA-explainability story gets stronger.
- Evidence/source: Richard's interview; backlog #15.

## NOT

- Explicit exclusions: no code changes, the audit is read-only; no writes to Jira/Confluence without human approval of each ticket.
- Protected areas: the scored decision path is FCA territory. The audit reads it and proposes changes only as tickets for human review.
- Agent must never: assert a mismatch without quoting both the doc passage and the code location.

## DONE

- Acceptance signals that pass or fail: every finding independently checkable (a human clicks the file:line and the doc link and sees what the report claims); at least one finding demoed end-to-end; zero unsourced claims.
- Authoritative verifier: human spot-check of ≥2 findings against source.

### Scenarios

```gherkin
Scenario: happy path
  Given a documented rule with a clear implementation
  When the audit runs
  Then the report marks it ALIGNED with doc quote and file:line reference

Scenario: edge case
  Given a documented rule the audit cannot locate in code
  When the audit runs
  Then the report marks it NOT FOUND and says where it looked

Scenario: explicit exclusion
  Given a mismatch on the scored decision path
  When the audit proposes realignment
  Then it drafts a ticket for human review and changes nothing itself
```