Traceability¶
Cross-cutting quality validation: horizontal consistency (MECE) and vertical traceability.
Last Updated: 2026-02-15
Level 0: Stakeholder Needs (WHY)¶
As a developer, I want to review all items on ONE level (US, REQ, or SPEC) for MECE properties, so that I catch redundancies, contradictions, gaps, and missing links within that level. Acceptance Scenarios:
|
As a developer, I want to trace ONE stakeholder need vertically through REQ → SPEC → Code → Test, so that I verify it’s fully implemented with meaningful links. Acceptance Scenarios:
|
Level 1: Requirements (WHAT)¶
Description: ubFlow SHALL provide a mece agent that analyzes ONE level (US, REQ, or SPEC) for MECE properties (Mutually Exclusive, Collectively Exhaustive). Rationale: Horizontal consistency within a level ensures no redundancies or contradictions. Focused scope prevents context overflow. Acceptance Criteria:
|
Description: ubFlow SHALL provide a trace agent that verifies ONE stakeholder need or requirement is fully traced through all levels (US → REQ → SPEC → Code → Test). Rationale: Vertical traceability ensures complete implementation. Semantic validation catches links that exist but don’t make sense. Acceptance Criteria:
|
Level 2: Design (HOW)¶
MECE Agent¶
Design: The MECE Agent analyzes ONE level at a time for Mutually Exclusive, Collectively Exhaustive properties. Scope: ┌──────────────────────────────────────────────────┐
│ NEED_001 ↔ NEED_002 ↔ NEED_003 ↔ NEED_004 │ ← MECE checks
└──────────────────────────────────────────────────┘
Horizontal only — vertical traceability is the Trace Agent’s job. Input: Level parameter (US, REQ, SPEC). Defaults to REQ if unspecified. Six Analysis Categories:
File: |
Design: The MECE Agent produces a structured report with categorized findings. Report Structure: # MECE Analysis Report
**Level**: US | REQ | SPEC
**Date**: YYYY-MM-DD
**Total Items Analyzed**: N
Summary Table: | Category | Count | Severity |
|-----------------|-------|----------|
| Redundancies | 0 | - |
| Contradictions | 0 | - |
| Gaps | 0 | - |
| Overlaps | 0 | - |
| Missing Links | 0 | - |
Findings by Severity:
Handoffs: After analysis, suggests |
Trace Agent¶
Design: The Trace Agent traces ONE item vertically through all levels (US → REQ → SPEC → Code → Test) and validates semantic correctness. Scope: ┌─────────────┐
│ NEED_CFG_001 │ ← START HERE
└──────┬──────┘
↓ :links:
┌──────┴──────┬──────────────┐
│ REQ_CFG_001 │ REQ_CFG_002 │ ← Find linked REQs
└──────┬──────┴──────┬───────┘
↓ ↓
┌──────┴──────┬──────┴───────┐
│SPEC_CFG_001 │SPEC_CFG_002 │ ← Find linked SPECs
└──────┬──────┴──────┬───────┘
↓ ↓
Code ←→ Tests ← Find implementation
Vertical only — horizontal consistency is the MECE Agent’s job. Input: Starting item (NEED_xxx or REQ_xxx). Asks user if unspecified. Four Check Types:
Link Discovery: # Trace downward with depth
get_need_links('NEED_xxx', max_depth=3)
# Trace upward (find needs linking TO this one)
find_needs(links='SPEC_xxx')
File: |
Design: The Trace Agent produces a report with a visual trace tree and coverage summary. Report Structure: # Trace Report: [NEED_ID]
**Date**: YYYY-MM-DD
**Starting Point**: [NEED_ID]
**Direction**: Downward | Upward | Both
Trace Tree Visualization: NEED_CFG_001: "Edit user settings"
├── REQ_CFG_001: "Allow email editing" ✅
│ ├── SPEC_CFG_001: "Settings form design" ✅
│ │ └── Code: src/settings.py ✅
│ └── Test: test_settings.py::test_email_edit ✅
├── REQ_CFG_002: "Persist to YAML" ✅
│ ├── SPEC_CFG_002: "YAML file format" ✅
│ │ └── Code: src/config.py ✅
│ └── Test: test_config.py::test_yaml_save ✅
└── REQ_CFG_003: "Validate email format" ⚠️
└── SPEC: MISSING ❌
Coverage Summary Table: Per-level counts of Total, Complete, and Missing items. Sections: Gaps Found, Semantic Issues, Recommendations. Handoffs: After analysis, suggests |
Quality Check Workflow¶
Design: MECE and Trace agents are usable as independent quality checks outside of a change workflow. Usage Modes:
Standalone Flow: Developer
│
├──→ @mece <level> ──→ Horizontal MECE Report
│
└──→ @trace <ID> ──→ Vertical Coverage Report
│
▼ (issues found?)
@change ──→ Fix via change workflow
Key Property: Quality checks are read-only — they never modify specification files. If issues are found, the developer starts a change workflow to fix them. |
Traceability¶
Stakeholder Needs¶
ID |
Title |
Status |
Priority |
|---|---|---|---|
Review Requirements for Consistency |
implemented |
high |
|
Trace Stakeholder Need Through All Levels |
implemented |
high |
Requirements¶
ID |
Title |
Status |
Tags |
|---|---|---|---|
MECE Requirements Review |
implemented |
traceability; agent; review; mece |
|
Vertical Traceability Verification |
implemented |
traceability; agent; trace; vertical |
Design Specifications¶
ID |
Title |
Status |
Links |
|---|---|---|---|
Horizontal MECE Analysis |
implemented |
||
MECE Report Format |
implemented |
||
Independent Quality Check Workflow |
implemented |
REQ_WF_QUALITY_INDEPENDENT; REQ_TRACE_MECE; REQ_TRACE_VERTICAL |
|
Trace Report Format |
implemented |
||
Vertical Traceability Analysis |
implemented |