Skip to main content

Use Case: Bidirectional Wiring Between BR/FR, Tasks, and Documentation

Type: Discovered Use Case (Promoted to Canonical)
ID: UC-D-002 → UC-050
Discovered: 2025-12-16
Promoted: 2025-12-16
Status: Active (Promoted)
Domain: Knowledge Base Management

Summary​

Every link between work items (BR/FR, Tasks, Documentation) must be bidirectional. If BR links to Task, Task must link back to BR. This ensures traceability and discoverability across the knowledge base.

Discovery Context​

How Discovered:

  • While wiring BR-002 to Task T06, recognized need for bidirectional links
  • User question: "is there wiring between the BR, task, and documentation?"
  • Pattern recognized: One-way links aren't sufficient for discoverability

Discovered During:

  • Work: BR-002/T06 wiring work
  • Date: 2025-12-16
  • Context: Ensuring all related work items are discoverable

Pattern Recognition:

  • Bidirectional links enable navigation from any starting point
  • One-way links create discoverability gaps
  • Pattern should be documented as principle

Use Case Description​

Actor: Project maintainers, developers, agents, knowledge base users
Goal: Ensure traceability and discoverability across all work items
Preconditions:

  • BR/FR, Task, or Documentation exists
  • Related work items exist

Postconditions:

  • All relationships are bidirectional
  • Can navigate from any work item to related items
  • Links are consistent and accurate

Main Flow:

  1. Create or update BR/FR, Task, or Documentation
  2. Identify related work items
  3. Add links from current item to related items
  4. Add links from related items back to current item
  5. Verify all links resolve correctly
  6. Document wiring principle (if not already documented)

Alternative Flows:

  • Flow A: New BR → Create Task → Wire both directions
  • Flow B: Discovered pattern → Create Documentation → Wire to work that revealed it

Discovery Rationale​

Why This Pattern Emerged:

  • One-way links limit discoverability
  • Need to navigate from any starting point
  • Consistency requires bidirectional links
  • Knowledge preservation requires complete relationships

Gap in Original Design:

  • Original design didn't explicitly require bidirectional links
  • No principle documented for wiring
  • Pattern wasn't part of framework design

Lessons Learned:

  • Bidirectional links are essential for discoverability
  • Pattern should be documented as principle
  • Should be part of framework design
  • Validation needed to ensure links exist

Implementation​

Related Work:

Wiring:

  • ✅ BR-002 links to Task T06
  • ✅ Task T06 links to BR-002
  • ✅ Documentation links to BR-002 and Task T06
  • ✅ BR-002 and Task T06 link to documentation
  • ✅ Use case links to all related work

Implementation Status:

  • Discovered
  • Documented
  • Wired to related work
  • Validated
  • Promoted to Canonical (UC-050)

Examples​

Example 1: BR-002 ↔ Task T06 ↔ Documentation

  • BR-002: Links to Task T06 and Documentation
  • Task T06: Links back to BR-002 and Documentation
  • Documentation: Links to BR-002 and Task T06
  • Result: Fully bidirectional, navigable from any starting point

Example 2: Pattern Discovery → Documentation → Wiring

  • Work: BR-002/T06 wiring work
  • Pattern: Bidirectional wiring principle
  • Documentation: BIDIRECTIONAL_WIRING_PRINCIPLE.md created
  • Wiring: All items bidirectionally linked

Promotion to Canonical​

Promotion Criteria:

  • Widely applicable across projects
  • Validated through usage
  • Represents best practice
  • Should be part of framework design

Promotion Status:

  • Not yet promoted
  • Under consideration
  • Promoted to UC-050

Promotion Notes:

  • Promoted: 2025-12-16
  • Rationale: Widely applicable, represents best practice, essential for knowledge base management
  • Canonical Use Case: UC-050 (Bidirectional Wiring Principle)
  • Status: Now part of framework design
  • Canonical: UC-050 (Bidirectional Wiring Principle) - Promoted version
  • Discovered: UC-D-001 (Re-opening BRs/Tasks) - Related pattern
  • Discovered: UC-D-003 (Pattern Discovery Workflow) - How this pattern was discovered

References​

Template Usage:

  • This use case follows the Discovered Use Case template
  • Demonstrates promotion to canonical
  • Shows bidirectional wiring

This use case is part of the Use Cases Knowledge Base. See docs/use-cases/USE_CASE_METHODOLOGY.md for methodology.