ADR-004: Hybrid Specification Strategy (Use Case + Gherkin)

Status: Proposed
Date: 2026-01-20
Context: Documentation Format for Legacy Business Logic

---

Decision

We adopt a Hybrid Specification approach using:

• Gherkin for State Machines and Internal Logic (automated testing potential).
• Use Cases for Human Workflows (onboarding and support documentation).

Context

The WepNG codebase contains undocumented business logic that needs to be reverse-engineered. A single format cannot efficiently capture:

1. Complex state transitions (Fee Lifecycle, Request Workflows).
2. Human-computer interactions (Assign Callback, Close Order).
3. Validation rules and constraints (Business Rules).

Considered Options

Option A: Gherkin Only

• Pros: Executable specs, BDD alignment.
• Cons: Verbose for simple CRUD workflows. Requires SpecFlow setup for execution.

Option B: Use Cases Only

• Pros: Human-readable, good for onboarding.
• Cons: Cannot be executed. Poor for complex conditional logic.

Option C: Hybrid (Recommended)

• Pros: Right tool for the right job.
• Cons: Requires guidelines to decide which format to use.

Rationale

Logic Type	Best Format	Example
State Machines	Gherkin + State Diagram	Fee Lifecycle, Refund Request
Human Workflows	Use Case	Assign Callback, Create Order
Validation Rules	Business Rule Index	BR-OMGT-001 (Callback Recipients)

Consequences

1. Folder Structure:

   • specs/current/[module]/dashboard_logic/ → Gherkin
   • specs/current/[module]/user_tasks/ → Use Cases
   • specs/draft/[module]/ → Work-in-progress (either format)

2. Validation Workflow:

   • Agent generates draft spec with > [!WARNING] Unverified Interpretation
   • Creator reviews and approves
   • Approved spec moves to specs/current/

3. Guidelines:

   • Gherkin Strategy
   • Use Case Strategy
   • Functional Strategy

References

• Functional Strategy
• Gherkin Best Practices