Skip to main content

Bug Report: Multiple Bugs in Kanban Package Installation Process

Type: Bug Report (BR)
Submitted: 2025-12-10
Submitted By: AI Agent (Cursor) acting as user/client for dev-toolkit
Priority: HIGH
Severity: HIGH
Status: PENDING

Implementing Task: E4:S09:T01 GitHub Issue: #9

Summary​

Multiple bugs in the Kanban package installation process prevent proper execution of canonical_adoption mode and intelligent task mapping. Bugs include missing imports, regex errors, mode mismatches, and incorrect analysis recommendations.

Description​

What is the bug?​

During UAT of the Kanban package installation process, multiple bugs were discovered that prevent the canonical_adoption mode from functioning correctly:

  1. Missing Tuple Import - analyze_structure.py uses Optional[Tuple] but Tuple is not imported
  2. Semantic Matcher Regex Error - Optional group handling causes "no such group" error
  3. Mode Mismatch - canonical_adoption mode supported by install script but not migrate script
  4. Incorrect Analysis Recommendations - Analysis recommends "fresh" mode despite detecting existing structure

What should happen vs. what actually happens?​

Expected Behavior:

  • Installation script runs without errors
  • Semantic matching loads canonical epic definitions successfully
  • Canonical adoption mode executes end-to-end
  • Analysis provides accurate recommendations based on detected structure

Actual Behavior:

  • Installation fails at analysis step due to missing Tuple import
  • Semantic matching fails silently with "no such group" error
  • Canonical adoption mode fails because migrate script doesn't support it
  • Analysis incorrectly recommends "fresh" mode despite detecting 9 epics, 40 stories, 291 tasks

When does it occur?​

These bugs occur when:

  • Running install_kanban_framework.py with existing Kanban structure
  • Attempting to use canonical_adoption mode
  • Running analysis step with semantic matching enabled
  • Migrating structure with canonical_adoption mode

Who is affected?​

  • Projects with existing Kanban structures attempting to adopt canonical structure
  • Users trying to use canonical_adoption mode
  • AI agents automating Kanban framework installation

Affected Component​

Primary Component: Kanban Framework - Installation Process
Affected Areas:

  • Installation Process
  • Migration Utilities
  • Analysis Utilities
  • Semantic Matching
  • Backend/API
  • Frontend/UI
  • Database/Schema
  • Integration/External Service

Root Cause:

  • Missing type imports (Tuple)
  • Incorrect regex pattern handling for optional groups
  • Inconsistent mode support across scripts
  • Flawed analysis recommendation logic

Steps to Reproduce​

Bug 1: Missing Tuple Import​

  1. Install Kanban package from ai-dev-kit
  2. Run python3 packages/frameworks/kanban/scripts/install_kanban_framework.py --mode canonical_adoption
  3. Installation reaches analysis step
  4. Error: NameError: name 'Tuple' is not defined at line 192 in analyze_structure.py

Bug 2: Semantic Matcher Regex Error​

  1. Run installation with existing Kanban structure
  2. Analysis step attempts to load canonical epic definitions
  3. Error: Error loading canonical epic definitions: no such group
  4. Semantic matching fails silently, returns 0 matches

Bug 3: Mode Mismatch​

  1. Run install_kanban_framework.py --mode canonical_adoption
  2. Installation completes analysis successfully
  3. Migration step calls migrate_structure.py --mode canonical_adoption
  4. Error: error: argument --mode: invalid choice: 'canonical_adoption'

Bug 4: Incorrect Analysis Recommendations​

  1. Run installation with existing Kanban structure (9 epics, 40 stories, 291 tasks)
  2. Analysis detects structure successfully
  3. Result: Analysis recommends "fresh" mode with rationale "No existing Kanban structure detected"
  4. Rationale contradicts detection results

Environment​

Environment: Development
Version: Kanban Framework v2.1.0
Repository: earlution/dev-toolkit (consuming ai-dev-kit framework)
Framework Source: earlution/ai-dev-kit
Framework Path: packages/frameworks/kanban/
Python Version: 3.x

Impact​

User Impact:

  • Critical - System unusable (for canonical adoption mode)
  • High - Major functionality broken
  • Medium - Some functionality affected
  • Low - Minor issue, workaround available

Business Impact:

  • Canonical adoption mode is non-functional
  • Users cannot leverage intelligent task mapping feature
  • Framework credibility affected by multiple blocking bugs

Workaround:

  • Bug 1: Add Tuple to imports manually (fixed locally during UAT)
  • Bug 2: Fix regex optional group handling (fixed locally during UAT)
  • Bug 3: Use hybrid mode instead (defeats purpose of canonical adoption)
  • Bug 4: Ignore recommendation and manually select mode

Acceptance Criteria (Fix Requirements)​

  • Criterion 1: analyze_structure.py imports Tuple from typing
  • Criterion 2: semantic_matcher.py handles optional regex groups correctly
  • Criterion 3: migrate_structure.py supports canonical_adoption mode in argparse
  • Criterion 4: Analysis recommendation logic correctly considers detected structure
  • Criterion 5: All bugs fixed and tested with real-world Kanban structures
  • Criterion 6: Installation completes successfully in canonical_adoption mode

Verification Method:

  • Manual testing (UAT scenario reproduction)
  • Test suite execution
  • Both

Fix Attempt History​

Purpose: This section documents all fix attempts for this bug.

Fix Attempts​

No fix attempts yet - bugs discovered during UAT

Dependencies​

Blocks:

  • Canonical adoption mode functionality
  • Intelligent task mapping feature
  • Framework adoption for projects with existing structures

Blocked By:

  • None

Related Work:

  • UXR-004: Kanban Package Installation UAT (comprehensive findings)
  • BR-008: Arbitrary 80% Threshold / No Agentic Intelligence
  • FR-010: Implement Actual Agentic Intelligence for Task Mapping

Intake Decision​

Intake Status: PENDING
Intake Date: 2025-12-10
Intake By: AI Agent (ai-dev-kit)

Decision Flow Results:

  • Story Match Found: [TBD]

Assigned To:

  • Epic: [TBD]
  • Story: [TBD]
  • Task: [TBD]
  • Version: [TBD]

Kanban Links:

  • Epic: [TBD]
  • Story: [TBD]
  • Task: [TBD]

Notes​

This bug report documents multiple bugs discovered during comprehensive UAT of the Kanban package installation process. All bugs were encountered when attempting to use canonical_adoption mode with an existing Kanban structure (9 epics, 40 stories, 291 tasks).

UAT Context:

  • Real-world installation scenario
  • Following package instructions exactly
  • Comprehensive documentation of all issues encountered

References​

  • UXR-004: Kanban Package Installation UAT (docs/project-management/kanban/fr-br/UXR-004-kanban-package-installation-uat.md)
  • Framework README: packages/frameworks/kanban/README.md
  • Installation Script: packages/frameworks/kanban/scripts/install_kanban_framework.py
  • Analysis Script: packages/frameworks/kanban/scripts/analyze_structure.py
  • Migration Script: packages/frameworks/kanban/scripts/migrate_structure.py
  • Semantic Matcher: packages/frameworks/kanban/scripts/semantic_matcher.py

Template Usage:

  • This BR follows the Kanban Framework BR template
  • Comprehensive bug documentation with reproduction steps
  • Clear acceptance criteria provided
  • Related work referenced

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