ldy26098
/
BMAD-METHOD
mirror of https://github.com/bmad-code-org/BMAD-METHOD.git
1
0
Fork 0
Code Packages Projects Releases Wiki Activity
BMAD-METHOD/devKalla-Fordonscervice/_wds/data/agent-guides/saga/strategic-documentation.md

9.3 KiB
Raw Blame History

Saga's Strategic Documentation Guide

When to load: When creating Product Brief, Project Outline, or any strategic documentation

Core Principle

Create documentation that coordinates teams and persists context.

Every project needs a North Star - clear, accessible, living documentation that guides all work.

The Project Outline

Created during Product Brief (Step 1), updated throughout project

Purpose

  • Single source of truth for project status
  • Coordination point for all team members
  • Context preservation across sessions
  • Onboarding tool for new collaborators

What Goes In Project Outline

project:
  name: [Project Name]
  type: [digital_product|landing_page|website|other]
  status: [planning|in_progress|complete]

methodology:
  type: [wds-v6|wps2c-v4|custom]
  instructions_file: [if custom]

phases:
  phase_1_product_brief:
    folder: "docs/A-Product-Brief/"
    name: "Product Exploration"
    status: [not_started|in_progress|complete]
    artifacts:
      - product-brief.md
      - pitch-deck.md (if created)
  
  phase_2_trigger_mapping:
    folder: "docs/B-Trigger-Map/"
    name: "Trigger Mapping"
    status: [not_started|in_progress|complete]
    artifacts:
      - trigger-map.md
      - trigger-map-diagram.mermaid
  
  # ... other phases

languages:
  specification_language: "en"
  product_languages: ["en", "se"]

design_system:
  enabled: true
  mode: [none|figma|component_library]
  library: [if mode=component_library]

When to Update Project Outline

Always update when:

  • ✅ Completing a phase
  • ✅ Creating new artifacts
  • ✅ Changing project scope
  • ✅ Adding new workflows

Project outline is living documentation - keep it current!

The Product Brief

10-step conversational workshop creates:

1. Vision & Problem Statement

What are we building and why?

  • Product vision (aspirational)
  • Problem statement (what pain exists)
  • Solution approach (high-level)

2. Positioning

How are we different?

  • Target customer
  • Need/opportunity
  • Product category
  • Key benefits
  • Differentiation vs competition

Format: "For [target] who [need], our [product] is [category] that [benefits]. Unlike [competition], we [differentiators]."

3. Value Trigger Chain (VTC)

Strategic benchmark for early decisions

Created in Step 4 (early in the brief) to provide strategic grounding:

  • Business goal
  • Solution context
  • User
  • Driving forces (positive + negative)
  • Customer awareness progression

See: VTC micro-guide for Freya (also relevant for Saga)

4. Business Model

How do we make money?

  • Revenue model (subscription, transaction, license, etc.)
  • Pricing approach
  • Unit economics
  • Key assumptions

5. Business Customers

Who pays? (B2B/Enterprise)

  • Decision makers
  • Budget owners
  • Procurement process
  • Deal cycle

Skip if B2C.

6. Target Users

Who actually uses it?

  • User segments
  • Demographics
  • Psychographics
  • Current behavior patterns

Note: Detailed in Trigger Map later, this is overview.

7. Success Criteria

How do we measure success?

  • Business metrics (revenue, users, retention)
  • User metrics (engagement, satisfaction, NPS)
  • Technical metrics (performance, uptime)
  • Timeline milestones

8. Competitive Landscape

Who else solves this?

  • Direct competitors
  • Indirect competitors
  • Substitutes
  • Our advantages/disadvantages

9. Unfair Advantage

What do we have that others can't easily copy?

  • Network effects
  • Proprietary data
  • Domain expertise
  • Strategic partnerships
  • Technology
  • Brand/reputation

10. Constraints

What are our limits?

  • Budget constraints
  • Timeline constraints
  • Technical constraints
  • Resource constraints
  • Regulatory constraints

11. Tone of Voice

How should UI microcopy sound?

  • Brand personality
  • Writing principles
  • Do's and don'ts
  • Example phrases

Used for: Field labels, buttons, error messages, success messages

NOT for: Strategic content (that uses Content Creation Workshop)

12. Synthesize

Bring it all together

Generate complete Product Brief document using template.

See: ../../workflows/1-project-brief/project-brief/complete/project-brief.template.md

File Naming Conventions

CRITICAL: Never use generic names

❌ Wrong (Generic)

  • README.md
  • guide.md
  • notes.md
  • documentation.md

Why bad: Ambiguous, unmaintainable, confusing

✅ Right (Specific)

  • product-brief.md
  • trigger-mapping-guide.md
  • platform-requirements.md
  • design-system-guide.md

Why better: Clear purpose, searchable, maintainable

Pattern: [TOPIC]-GUIDE.md

For methodology documentation:

  • phase-1-product-exploration-guide.md
  • value-trigger-chain-guide.md
  • content-creation-philosophy.md

For deliverables:

  • product-brief.md
  • trigger-map.md
  • platform-prd.md

For examples:

  • wds-examples-guide.md
  • wds-v6-conversion-guide.md

Documentation Quality Standards

Precision

Articulate requirements with precision while keeping language accessible

❌ "Users probably want something to help them..."

✅ "Consultants need proposal templates that reduce formatting time by 80% while maintaining professional appearance"

Evidence

Ground all findings in verifiable evidence

❌ "Most consultants struggle with proposals"

✅ "In 15 user interviews, 12 consultants (80%) reported spending 3+ hours per proposal on formatting alone"

Accessibility

Technical accuracy, but readable by non-experts

❌ "Implement OAuth 2.0 authorization code flow with PKCE extension for SPA-based authentication"

✅ "Use industry-standard secure login (OAuth 2.0) that protects user data even in browser-based apps"

Structure

Clear hierarchy, scannable, actionable

Good structure:

# Main Topic

## Overview
[High-level summary]

## Key Concepts
### Concept 1
[Explanation]

### Concept 2
[Explanation]

## How to Use This
[Actionable steps]

## Related Resources
[Links to related docs]

The Bible: project-context.md

If this file exists, treat it as gospel.

What It Contains

  • Project history
  • Key decisions and rationale
  • Technical constraints
  • Business constraints
  • Team context
  • Anything critical to know

How to Use It

  1. First action: Check if exists
  2. If exists: Read thoroughly before any work
  3. If missing: Offer to create one

Location: Usually docs/project-context.md or root project-context.md

Absolute vs Relative Paths

WDS uses absolute paths for artifacts:

✅ Absolute (Explicit)

docs/A-Product-Brief/product-brief.md
docs/B-Trigger-Map/trigger-map.md
docs/C-Scenarios/landing-page/01-hero-section.md

Why: Clear, unambiguous, no confusion about location

❌ Relative (Ambiguous)

../product-brief.md
../../trigger-map.md

Why bad: Depends on current location, breaks easily

Alliterative Persona Names

Create memorable, fun persona names using alliteration

Good Examples

  • Harriet the Hairdresser
  • Marcus Manager
  • Diana Designer
  • Samantha Salesperson
  • Tony Trainer
  • Petra Product Manager

Why: Easier to remember, more human, makes documentation engaging

Bad Examples

  • John (generic)
  • User 1 (impersonal)
  • Target Group A (clinical)

Why bad: Forgettable, boring, doesn't bring persona to life

Documentation Maintenance

Documents are living artifacts:

When to Update

  • ✅ New information discovered
  • ✅ Assumptions proven wrong
  • ✅ Priorities shift
  • ✅ Scope changes
  • ✅ Phase completes

Version Control

  • Use git for all documentation
  • Commit with clear messages
  • Tag major milestones
  • Keep history

Archive, Don't Delete

  • Old versions have context value
  • Create archive/ folder if needed
  • Document why something changed

Documentation Handoffs

When handing to development team:

Complete Package Includes

  1. Product Brief - Strategic foundation
  2. Trigger Map - User psychology
  3. Platform PRD - Technical requirements
  4. Page Specifications - Detailed UX specs
  5. Design System (if created) - Component library
  6. Design Delivery PRD - Complete handoff package

See: Phase 6 (Design Deliveries) for handoff process

Quality Checklist

Before marking documentation "complete":

  • Clear purpose - Why does this document exist?
  • Specific names - No README.md or generic.md?
  • Absolute paths - All file references explicit?
  • Evidence-based - Claims backed by research/data?
  • Accessible language - Readable by all stakeholders?
  • Structured well - Scannable, logical hierarchy?
  • Up to date - Reflects current reality?
  • Actionable - Others can use this to make decisions?

Related Resources

  • Product Brief Workflow: ../../workflows/1-project-brief/project-brief/
  • File Naming Conventions: ../../workflows/00-system/FILE-NAMING-CONVENTIONS.md
  • Project Outline Template: Created during Phase 1 Step 1
  • Documentation Standards: ../../../bmm/data/documentation-standards.md

Good documentation is the foundation of coordinated, confident execution. It's not overhead - it's leverage.