Skip to main content

Bug Report: RW Doc-Init Detection Bug (Story + Task Docs Batch Creation)

Type: Bug Report (BR)
Submitted: 2025-12-18
Submitted By: User (discovered during E4:S13:T04)
Priority: HIGH
Severity: HIGH
Status: FIXED

Summary​

Release Workflow (RW) doc-init detection logic incorrectly sets BUILD=0 instead of BUILD=1 when Story + all Task docs are created together in story's abstract space (v0.E.S.0+0), then first implementation work begins on a task. The bug occurs because the detection function doesn't check if the task document already exists (even if not created in the current commit).

Description​

What is the bug? The detect_first_time_est_doc function in validate_version_bump.py incorrectly identifies first implementation work as doc-init (BUILD=0) when:

  1. Story + all Task docs created together in story's abstract space (v0.E.S.0+0)
  2. Task document already exists (from previous commit)
  3. No task-level version exists yet (no S.T+* version in history)
  4. First implementation work begins (code changes, not docs-only)

What should happen vs. what actually happens?

  • Expected: RW should detect that Task document already exists → NOT doc-init → BUILD=1 (first functional build)
  • Actual: RW incorrectly detects this as doc-init → BUILD=0 (incorrect version)

When does it occur?

  • When Story + all Task docs are created together in a single commit (story's abstract space)
  • When first implementation work begins on any task (code changes present)
  • During Release Workflow Step 2 (Bump Version)
  • When no task-level version exists yet (no prior S.T+* version in history)

Who is affected?

  • Developers using batch creation workflow (Story + Task docs together)
  • Release Workflow execution (incorrect versioning)
  • Version tracking accuracy (BUILD=0 instead of BUILD=1)

Valid Use Case: This bug was exposed by a valid use case: Story + Task docs batch creation. The workflow is legitimate and efficient, but exposed a design flaw in state detection logic.

Affected Component​

Primary Component: Release Workflow Validation Scripts
Affected Areas:

  • Backend/API
  • Frontend/UI
  • Database/Schema
  • Integration/External Service
  • Documentation
  • Other: Validation Scripts, Version Bump Logic

Root Cause: The detect_first_time_est_doc function in validate_version_bump.py has flawed logic:

  • Function checks if task doc was created in THIS commit
  • Function checks if prior version exists
  • Missing Check: Function doesn't verify if task doc already exists (even if not created in this commit)
  • Flawed Assumption: "No prior version = doc-init"

Design Flaw Pattern: This represents an abstract anti-pattern: Use Case Exposed Design Flaw

  • Valid use case (Story + Task docs batch creation) exists
  • Use case exposes design flaw (state detection logic)
  • Flaw is fixed, but use case remains relevant as knowledge

Steps to Reproduce​

  1. Create Story document (e.g., Story-013-kanban-board-moscow-prioritized-task-view.md)
  2. Create all Task documents for that Story in the same commit
  3. Commit all documents together in story's abstract space (v0.E.S.0+0)
  4. Begin implementation work on Task 1 (make code changes, not just docs)
  5. Run Release Workflow (RW) to version the work
  6. Expected result: RW detects task doc exists → BUILD=1 (first functional build)
  7. Actual result (before fix): RW incorrectly detects doc-init → BUILD=0 (incorrect)

Example Scenario:

Commit 1: Story + Task docs created together
- Story-013-kanban-board-moscow-prioritized-task-view.md
- T01-kanban-board-moscow-prioritized-task-view.md
- T02-update-kanban-governance-policy.md
- T03-update-kanban-board-template.md
- T04-assess-system-impacts.md
- T05-update-kanban-package.md
- T06-update-other-affected-packages.md
Version: v0.4.13.0+0 (story creation, doc-init)

Commit 2: First implementation work on T01
- Code changes in kboard.md
- Run RW
- Expected: v0.4.13.1+1 (first functional build)
- Actual (before fix): v0.4.13.1+0 (incorrect doc-init)

Environment​

Environment: Development
Version: v0.4.13.4+1 (bug fixed)
Browser/Platform: N/A
OS: macOS (darwin 24.6.0)

Affected Systems:

  • Release Workflow (RW) Step 2 (Bump Version)
  • Version validation scripts
  • Any project using batch creation workflow

Impact​

User Impact:

  • Critical - System unusable
  • High - Major functionality broken (incorrect versioning)
  • Medium - Some functionality affected
  • Low - Minor issue, workaround available

Business Impact:

  • Incorrect version numbers (BUILD=0 instead of BUILD=1)
  • Version tracking accuracy compromised
  • Changelog entries show incorrect build numbers
  • Forensic traceability affected

Workaround:

  • Create Task documents separately (not in batch with Story)
  • Manually correct version after RW runs
  • Avoid batch creation workflow (not recommended - workflow is valid)

Acceptance Criteria (Fix Requirements)​

  • Function checks if task document already exists (even if not created in this commit)
  • Function correctly identifies when task doc exists from previous commit
  • Function sets BUILD=1 (not BUILD=0) when task doc exists and code changes present
  • Function only returns is_first_time = True if task doc is created in THIS commit AND docs-only AND no prior version
  • Documentation updated with new use case scenario and fix explanation

Verification Method:

  • Test suite execution
  • Manual testing
  • Both

Fix Verification Status:

  • Verified (test suite passed / manual test passed)
  • Attempted Fix (pending verification)
  • Fix Failed (bug still present)

Fix Attempt History​

Purpose: This section documents all fix attempts for this bug, ensuring that if a bug isn't squashed, the next build can be informed by previous attempts.

How to Use:

  • Each release that attempts to fix this bug should add a new entry to this section
  • Document what was attempted, what worked, what didn't, and verification status
  • This creates a knowledge base for future fix attempts

Fix Attempts​

Attempt 1: v0.4.13.4+1 - 2025-12-18​

Fix Description: Updated detect_first_time_est_doc function in validate_version_bump.py to check if task document already exists before determining doc-init state. Added task document existence check using locate_task_doc function.

Changes Made:

  • Added check: If task document already exists (using locate_task_doc function) → NOT doc-init
  • If task doc exists but wasn't created in this commit → is_first_time = False → BUILD=1
  • Only returns is_first_time = True if task doc is created in THIS commit AND docs-only AND no prior version
  • Updated RW execution guide documentation with new use case scenario (Example 4)
  • Updated T04 task document with bug analysis and fix

Files Updated:

  • packages/frameworks/workflow mgt/scripts/validation/validate_version_bump.py (bug fix)
  • packages/frameworks/workflow mgt/KB/Documentation/Developer_Docs/vwmp/release-workflow-agent-execution.md (documentation)
  • docs/project-management/kanban/epics/Epic-4/Story-013-kanban-board-moscow-prioritized-task-view/T04-assess-system-impacts.md (task doc)

Verification Status:

  • Verified (test suite passed / manual test passed)
  • Attempted Fix (pending verification)
  • Fix Failed (bug still present)

Verification Method:

  • Test suite execution
  • Manual testing
  • Both

Verification Evidence:

  • Manual test: Story + Task docs created together → First implementation work → BUILD=1 ✅ (correct)
  • Function correctly identifies when task doc exists from previous commit
  • Function sets BUILD=1 when task doc exists and code changes present
  • Function only returns is_first_time = True for actual doc-init scenarios

Result:

  • Bug Fixed
  • Bug Partially Fixed (describe partial fix)
  • Bug Not Fixed (describe why fix didn't work)

Lessons Learned:

  • Always check for object existence, not just creation events
  • Verify state independently of operation context
  • Don't assume "no prior version = first time"
  • Consider batch operations and parent-child relationships when designing state detection
  • Valid use cases can expose design flaws (abstract anti-pattern)

Next Steps:

  • None - bug is fixed
  • Use case remains relevant as knowledge (abstract anti-pattern)

Dependencies​

Blocks:

  • Correct versioning for batch creation workflow
  • Accurate version tracking and changelog entries

Blocked By:

  • None

Related Work:

  • Epic 4: Kanban Framework
  • Story 13: Kanban Board Enhancement - MoSCOW Prioritized Task View
  • Task 4: E4:S13:T04 – Assess system impacts (bug fixed here)
  • Use Case: UC-D-004 – Story + Task Docs Batch Creation
  • Abstract Anti-Pattern: Use Case Exposed Design Flaw

Intake Decision​

Intake Status: ACCEPTED
Intake Date: 2025-12-18
Intake By: User (discovered during T04 work)

Decision Flow Results:

  • Story Match Found: Epic 4, Story 13 → Task 4 (already in progress)

Assigned To:

  • Epic: Epic 4 - Kanban Framework
  • Story: Story 13 - Kanban Board Enhancement - MoSCOW Prioritized Task View
  • Task: E4:S13:T04 – Assess system impacts
  • Version: v0.4.13.4+1

Implementation Status: FIXED (v0.4.13.4+1)
Implementation Date: 2025-12-18
Verification Status: Verified (manual test passed)

Kanban Links:

Notes​

  • Valid Use Case: This bug was exposed by a legitimate workflow (Story + Task docs batch creation)
  • Abstract Anti-Pattern: The use case represents an abstract anti-pattern: Use Case Exposed Design Flaw
  • Knowledge Value: The use case remains relevant even after the bug is fixed, as it warns about flawed design assumptions
  • Pattern Recognition: This pattern can help identify similar design flaws in other systems
  • Design Flaw: The bug represents a "State Detection Logic Flaw" pattern (checking creation events instead of object existence)

Related Knowledge:

References​

  • packages/frameworks/workflow mgt/scripts/validation/validate_version_bump.py - Bug location and fix
  • packages/frameworks/workflow mgt/KB/Documentation/Developer_Docs/vwmp/release-workflow-agent-execution.md - RW documentation
  • docs/knowledge/use-cases/discovered/UC-D-004-story-task-docs-batch-creation.md - Discovered use case
  • docs/knowledge/analysis/abstract-anti-patterns-use-case-exposed-design-flaw.md - Abstract anti-pattern definition
  • docs/project-management/kanban/epics/Epic-4/Story-013-kanban-board-moscow-prioritized-task-view/T04-assess-system-impacts.md - Task document

Template Usage:

  • This BR follows the Kanban Framework BR template
  • Intake decision links to Epic 4, Story 13, Task 4
  • Fix attempt documented with complete details
  • Bidirectionally wired to use case and abstract anti-pattern documents

This template is part of the Kanban Framework. See packages/frameworks/kanban/ for complete framework documentation.