mouc 0.1.2

A lightweight dependency tracking system for mapping technical capabilities to user stories and outcomes

Mouc - Mapping Outcomes User stories and Capabilities

A lightweight dependency tracking system for software development that maps relationships between technical capabilities, user stories, and organizational outcomes.

Overview

Mouc helps engineering teams track and visualize dependencies between:

• Capabilities - Technical work your team builds
• User Stories - What other teams need from you
• Outcomes - Business/organizational goals that depend on the work

This is not a project management system. It's a technical dependency tracker that answers "what depends on what" and "what blocks what."

Installation

Install with uv (recommended):

uv pip install mouc

Or with pip:

pip install mouc

Quick Start

1. Create a feature_map.yaml file:

metadata:
  version: 1.0
  team: middleware_platform

entities:
  message_bus:
    type: capability
    name: Inter-Process Message Bus
    description: |
      High-performance message passing system for services.
      Provides reliable, ordered message delivery.
    dependencies: []
    links:
      - jira:INFRA-123
    tags: [infrastructure]

  service_communication:
    type: user_story
    name: Service Communication
    description: Frontend team needs services to communicate
    dependencies: [message_bus]
    meta:
      requestor: frontend_team
    links:
      - jira:STORY-456

  q3_launch:
    type: outcome
    name: Q3 Product Launch
    description: Launch new product features in Q3
    dependencies: [service_communication]
    links:
      - jira:EPIC-789
    meta:
      target_date: 2024-Q3

2. Generate documentation:

mouc doc

3. Generate dependency graph:

mouc graph all > deps.dot
dot -Tpng deps.dot -o deps.png

Commands

Documentation Generation

Generate markdown documentation from your feature map:

mouc doc                           # Output to stdout
mouc doc --output docs.md          # Output to file
mouc feature_map.yaml doc          # Specify input file

Graph Generation

Generate dependency graphs in DOT format:

# All entities and relationships
mouc graph --view all

# Critical path to a specific outcome
mouc graph --view critical-path --target q3_launch

# Filter by tags
mouc graph --view filtered --tags infrastructure monitoring

# Timeline view grouped by timeframe
mouc graph --view timeline

# Timeframe-colored view (colors indicate time progression)
mouc graph --view timeframe-colored

Render graphs with Graphviz:

mouc graph --view all | dot -Tpng -o graph.png
mouc graph --view all | dot -Tsvg -o graph.svg

YAML Schema

Full Example

metadata:
  version: 1.0
  last_updated: 2024-01-15
  team: middleware

entities:
  lock_free_queue:
    type: capability
    name: Lock-Free Queue Implementation
    description: |
      High-performance thread-safe queue using atomic operations.
      
      Performance targets:
      - 10M ops/sec single producer/consumer
      - Sub-microsecond latency at p99
    dependencies: []  # List of entity IDs this depends on
    links:
      - design:[DD-123](https://docs.google.com/document/d/abc123)
      - jira:INFRA-456
    tags: [critical, performance]  # Arbitrary tags

  message_bus:
    type: capability
    name: Inter-Process Message Bus
    description: Reliable message passing built on lock-free queue
    dependencies: [lock_free_queue]
    links:
      - jira:INFRA-789
    tags: [infrastructure]
    meta:
      timeframe: Q1 2025  # Optional: for timeline view

  analytics_realtime:
    type: user_story
    name: Real-time Analytics Pipeline
    description: |
      Analytics team needs to process streaming data at 100Hz
      with strict latency requirements.
    dependencies: [message_bus]  # Can depend on capabilities or other user stories
    meta:
      requestor: analytics_team  # Who asked for this
    links:
      - jira:STORY-100
    tags: [q2_commitment]

  mobile_app:
    type: outcome
    name: Mobile App Launch
    description: Launch new mobile application by Q3
    dependencies: [analytics_realtime]  # Can depend on user stories or capabilities
    links:
      - jira:EPIC-1000  # Always present for exec visibility
    meta:
      target_date: 2024-Q3
    tags: [company_priority]

Field Reference

Required fields for all entities:

• type: Entity type (capability, user_story, or outcome)
• name: Human-readable name
• description: Can be single line or multi-paragraph markdown

Optional fields for all entities:

• dependencies: List of entity IDs this depends on
  • Capabilities can only depend on other capabilities
  • User stories can depend on capabilities or other user stories
  • Outcomes can depend on any entity (capabilities, user stories, or other outcomes)
• links: List of links in various formats:
  • design:[DD-123](https://...) - Design doc with markdown link
  • jira:TICKET-123 - Jira ticket reference
  • https://... - Plain URL
• tags: List of arbitrary tags
• meta: Dictionary of metadata. Common fields include:
  • timeframe: Time period for timeline view (e.g., "Q1 2025", "Sprint 23")
  • requestor: Team or person requesting (for user stories)
  • target_date: Target completion date (for outcomes)

Use Cases

Find Critical Path

What needs to be done for the Q3 launch?

mouc graph --view critical-path --target q3_launch | dot -Tpng -o critical_path.png

Filter by Team

What infrastructure work is planned?

mouc graph --view filtered --tags infrastructure | dot -Tpng -o infra_work.png

Generate Reports

Create documentation for architecture review:

mouc doc --output architecture_review.md

View Timeline

Group work by time periods (quarters, sprints, etc.):

# Add timeframe metadata to entities:
# meta:
#   timeframe: "Q1 2025"

# Clustered by timeframe
mouc graph --view timeline | dot -Tpng -o timeline.png

# Colored by timeframe
mouc graph --view timeframe-colored | dot -Tpng -o timeframe_colored.png

Best Practices

1. Keep it current: Update dependencies when architecture changes
2. Don't over-specify: Only use fields you need
3. Rich descriptions: Spend time documenting critical capabilities
4. Consistent tags: Agree on tag conventions with your team
5. Version control: Keep feature_map.yaml in git
6. Review regularly: Quarterly reviews to prune obsolete items

Development

Setup

# Clone the repository
git clone https://github.com/rnortman/mouc.git
cd mouc

# Install with development dependencies
uv pip install -e ".[dev]"

Testing

# Run tests
pytest

# Run with coverage
pytest --cov=mouc

# Type checking
pyright

# Linting
ruff check src tests
ruff format src tests

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes with tests
4. Run linting and tests
5. Submit a pull request

License

MIT License - see LICENSE file for details