Change Management¶
Full change lifecycle: analyze, implement, verify, and recover.
Last Updated: 2026-02-15
Level 0: Stakeholder Needs (WHY)¶
Change Management Stakeholder Needs¶
Stories covering the full change lifecycle: analyze, implement, verify, recover.
Last Updated: 2026-02-06
As a developer, I want to have an agent analyze my change request against existing Stakeholder Needs, Requirements, and Specs, so that I understand the full impact before coding. Acceptance Scenarios:
|
As a developer, I want to have an agent implement changes with automatic traceability, so that I don’t have to manually link docs, code, and tests. Acceptance Scenarios:
|
As a developer, I want to verify that implementation matches the change proposal, so that I don’t miss requirements or acceptance criteria. Acceptance Scenarios:
|
As a developer, I want to recover gracefully when an agent fails mid-operation, so that I don’t end up with inconsistent state between docs and code. Acceptance Scenarios:
|
As a developer, I want to have the change agent work iteratively through specification levels (Stakeholder Need → Requirements → Design) with a persistent change document, so that large projects don’t overflow context and I have a complete change history. Acceptance Scenarios:
|
Level 1: Requirements (WHAT)¶
Change Management Requirements¶
Requirements for the change analysis, implementation, and verification workflow.
Last Updated: 2026-02-06
Description: ubFlow SHALL provide a change agent that:
Rationale: The change agent has full context during analysis and should capture this in the specification immediately. Separating analysis from spec-writing would require duplicate work and risk information loss. Acceptance Criteria:
|
Description: ubFlow SHALL provide an implement agent that:
Rationale: The Change Document provides focused context. The implement agent works only with the pre-identified scope, avoiding context overflow. Acceptance Criteria:
|
Description: ubFlow SHALL provide a verify agent that validates implementation completeness against the change proposal. Rationale: Verification ensures no requirements are missed and traceability is complete. Acceptance Criteria:
|
Description: ubFlow SHALL suggest appropriate next workflow steps after agent completion. Rationale: Users need guidance on which agent to invoke next based on the current workflow state. This reduces cognitive load and ensures the correct workflow is followed. Acceptance Criteria:
|
Iterative Change Processing¶
Description:
The Change Agent SHALL use Sphinx-Needs links (via Rationale: Automatic link discovery prevents manual searching and ensures all impacted elements are found. Acceptance Criteria:
|
Description: The Change Agent SHALL maintain a persistent Change Document in Markdown that records all analysis, decisions, and changes. Rationale: A persistent document provides context across sessions, enables review, and creates audit trail. Acceptance Criteria:
|
Description: The Change Agent SHALL perform horizontal consistency check within each level before proceeding to the next. Rationale: Catching conflicts early prevents cascading issues at lower levels. Acceptance Criteria:
|
Description: The Change Agent SHALL support navigation back to previous levels when issues are discovered. Rationale: Design feasibility issues may require requirement changes, which may require stakeholder need adjustments. Acceptance Criteria:
|
Description: The Change Agent SHALL perform final consistency check across all levels after completing the Design level. Rationale: Bidirectional navigation can introduce inconsistencies that need final verification before implementation. Acceptance Criteria:
|
Level 2: Design (HOW)¶
Change Agent Design¶
Design specifications for the Change Agent — iterative level-based change analysis.
Document Version: 0.1 Last Updated: 2026-02-06
Design: The Change Agent processes change requests one level at a time, following the hierarchy US → REQ → SPEC with user discussion at each level. Level Definitions:
Processing Flow per Level:
Don’t Skip Levels Rule: Even if the answer seems obvious, the agent processes each level systematically to ensure complete traceability (US → REQ → SPEC). Link Discovery: Uses ubCode MCP Server tools to find impacted elements: # Find linked items for a specific ID
find_needs(need_id='<ID>')
# Trace with depth
get_need_links('<ID>', max_depth=3)
File: |
Design: The Change Agent maintains a persistent Markdown document that records all analysis, decisions, and changes throughout the process. Lifecycle:
Location: Content Modes:
Example (during analysis): ## Level 1: Requirements
### New Requirements
#### REQ_REL_SEMVER: Semantic Versioning
```rst
.. req:: Semantic Versioning
:id: REQ_REL_SEMVER
:status: draft
...
```
Example (after approval): ## Level 1: Requirements
### New Requirements
- REQ_REL_SEMVER: Semantic Versioning
- REQ_REL_GITHUB_PUBLISH: GitHub Release Publication
|
Design: The Change Agent supports navigating back to any previous level when design feasibility issues or requirement adjustments are needed. Trigger: User says “go back to requirements” or “the stakeholder need needs adjustment” at any point during analysis. Navigation Procedure:
Preservation: Previous level work is preserved in the Change Document. Each iteration is marked so the full decision history is retained. Rationale: Design feasibility issues may require requirement changes, which may require stakeholder need adjustments. Linear-only processing would force restarting the entire analysis. |
Design: RST files are only updated after final approval of all levels together, never during analysis. This prevents broken cross-level links. Status Lifecycle:
Final Consistency Check (before writing RST):
After Writing:
Rationale: Atomic updates ensure |
Implement Agent Design¶
Design specifications for the Implement Agent — code implementation with traceability.
Document Version: 0.1 Last Updated: 2026-02-06
Design: The Implement Agent checks for sphinx-needs availability before starting work. Check Sequence:
Rationale: Cloud environments or fresh checkouts may lack dependencies. Catching this early avoids mid-implementation failures. File: |
Design: The Implement Agent reads the Change Document to determine implementation scope and then queries linked specs for detailed instructions. Input Resolution: The Change Document can come from:
Consumption Workflow:
Scope Constraint: The Implement Agent works only with pre-identified scope from the Change Document, avoiding context overflow. Boundary Rules:
|
Design: The Implement Agent runs sphinx-build as quality gate before and after coding. Quality Gate Workflow:
Commands: # Build docs (validates all)
sphinx-build -b html docs docs/_build/html -W --keep-going
# Run tests
pytest tests/ -v
Fail-Fast Rule: If pre-implementation build fails, the agent fixes documentation issues before touching any code. |
Design: All code and tests written by the Implement Agent include traceability comments linking back to Design Specs and Requirements. Code Traceability Format: # Implementation: SPEC_xxx
# Requirements: REQ_xxx_1, REQ_xxx_2
def my_function():
"""
Brief description.
Implements:
- REQ_xxx_1: [What this satisfies]
- SPEC_xxx: [Design reference]
"""
pass
Test Traceability Format: class TestFeatureName:
"""
Tests for REQ_xxx_1, REQ_xxx_2
"""
def test_acceptance_criteria_1(self):
"""
Verifies: REQ_xxx_1 AC-1
"""
pass
Commit Traceability Format: feat: [Feature name]
Implements: [Change Document name]
Requirements:
- REQ_xxx_1: [description]
Design:
- SPEC_xxx_1: [description]
Rationale: Traceability comments enable the Verify Agent and Trace Agent to validate implementation coverage without parsing complex code logic. |
Verify Agent Design¶
Design specifications for the Verify Agent — implementation verification and status lifecycle.
Document Version: 0.1 Last Updated: 2026-02-06
Design: The Verify Agent validates implementations across five categories, each with specific check questions. Category 1 — Requirements Verification: Check | Question |
Exists | Is REQ_xxx documented? |
Complete | Does it have all required fields (status, priority, AC)? |
Implemented | Is there a SPEC linking to it? |
Tested | Is there a test referencing it? |
Category 2 — Design Verification: Check | Question |
Exists | Is SPEC_xxx documented? |
Linked | Does it reference requirements? |
Implemented | Is there code implementing it? |
Accurate | Does code match the design? |
Category 3 — Code Verification: Check | Question |
Traceability | Does code reference SPEC IDs? |
Completeness | Are all design items implemented? |
Quality | Does it follow project conventions? |
Category 4 — Test Verification: Check | Question |
Coverage | Is every Acceptance Criterion tested? |
References | Do tests reference REQ IDs? |
Passing | Do all tests pass? |
Category 5 — Traceability Verification: Bidirectional link chain: REQ → SPEC → Code → Test
↑ ↑ ↑ ↑
└──────┴──────┴──────┘ (all linked back)
Common Issues Checklist:
File: |
Design: The Verify Agent produces a structured Verification Report with coverage matrix and issue tracking. Report Header: # Verification Report: [Feature/Change Name]
**Date**: YYYY-MM-DD
**Change Proposal**: [reference]
**Status**: ✅ PASSED | ⚠️ PARTIAL | ❌ FAILED
Summary Table: | Category | Total | Verified | Issues |
|----------------|-------|----------|--------|
| Requirements | n | n | 0 |
| Designs | n | n | 0 |
| Implementations| n | n | 0 |
| Tests | n | n | 0 |
| Traceability | n | n | 0 |
Requirements Coverage Matrix: Per-REQ row showing SPEC link, Code presence, Test presence, and Status. Acceptance Criteria Verification: Per-REQ section listing each AC with test mapping: ### REQ_xxx_1
- [x] AC-1: [criterion] → Test: test_module.py::test_ac1
- [ ] AC-2: [criterion] → **MISSING TEST**
Issue Format: Each issue includes: Severity (High/Medium/Low), Category, Description, Expected vs Actual, and Recommendation. |
Design:
The Verify Agent manages the Transition Rules:
Severity Levels and Actions:
Status Update Process: # Edit docs/11_requirements/req_*.rst
# Edit docs/12_design/spec_*.rst
# Change :status: approved → :status: implemented for verified items
git commit -m "docs: mark verified specs as implemented"
Rationale: Status reflects actual verification, not just code existence.
Only the Verify Agent updates status to |
Traceability¶
Stakeholder Needs¶
ID |
Title |
Status |
Priority |
|---|---|---|---|
Analyze Changes Before Implementation |
implemented |
mandatory |
|
Implement with Full Traceability |
implemented |
mandatory |
|
Iterative Level-Based Change Analysis |
implemented |
mandatory |
|
Recover from Agent Failures |
draft |
medium |
|
Verify Implementation Completeness |
implemented |
mandatory |
Requirements¶
ID |
Title |
Status |
Tags |
|---|---|---|---|
Change Analysis Agent |
implemented |
agent; change |
|
Bidirectional Level Navigation |
implemented |
agent; change; navigation |
|
Persistent Change Document |
implemented |
agent; change; document |
|
Final Consistency Check |
implemented |
agent; change; verification |
|
Implementation Agent with Full Traceability |
implemented |
agent; implementation |
|
Sphinx-Needs Link Discovery |
implemented |
agent; change; links |
|
Horizontal MECE Check per Level |
implemented |
agent; change; mece |
|
Verification Agent |
implemented |
agent; verification |
|
Workflow Step Suggestions |
implemented |
agent; handoffs; workflow |
Design Specifications¶
ID |
Title |
Status |
Links |
|---|---|---|---|
Atomic RST Updates with Status Lifecycle |
implemented |
REQ_CHG_ANALYSIS_AGENT; REQ_CHG_FINAL_CHECK; REQ_CHG_MECE_PER_LEVEL; SPEC_CHG_LEVEL_PROCESSING |
|
Bidirectional Level Navigation |
implemented |
||
Change Document Management |
implemented |
||
Iterative Level Processing |
implemented |
REQ_CHG_ANALYSIS_AGENT; REQ_CHG_WORKFLOW_STEPS; REQ_CHG_LINK_DISCOVERY; REQ_DX_AGENT_SELECTION_MENUS |
|
Change Document Consumption |
implemented |
||
Code and Test Traceability |
implemented |
||
Pre-Implementation Environment Check |
implemented |
||
Implementation Quality Gates |
implemented |
||
Five-Category Verification |
implemented |
||
Verification Report Format |
implemented |
||
Verification Status Lifecycle |
implemented |