docs: update all documentation and add AI tooling configs
- Rewrite README.md with current architecture, features and stack - Update docs/API.md with all current endpoints (corporate, BI, client 360) - Update docs/ARCHITECTURE.md with cache, modular queries, services, ETL - Update docs/GUIA-USUARIO.md for all roles (admin, corporate, agente) - Add docs/INDEX.md documentation index - Add PROJETO.md comprehensive project reference - Add BI-CCC-Implementation-Guide.md - Include AI agent configs (.claude, .agents, .gemini, _bmad) - Add netbird VPN configuration - Add status report Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
454
_bmad/wds/data/agent-guides/saga/strategic-documentation.md
Normal file
454
_bmad/wds/data/agent-guides/saga/strategic-documentation.md
Normal file
@@ -0,0 +1,454 @@
|
||||
# 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
|
||||
|
||||
```yaml
|
||||
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. Strategic Context (from Trigger Map)
|
||||
**Strategic benchmark for early decisions**
|
||||
|
||||
Extracted from the Trigger Map to provide strategic grounding:
|
||||
- Business goal
|
||||
- Solution context
|
||||
- Target group / persona
|
||||
- Driving forces (positive + negative)
|
||||
- Customer awareness progression
|
||||
|
||||
---
|
||||
|
||||
### 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. Create Product Brief
|
||||
**Bring it all together**
|
||||
|
||||
Generate complete Product Brief document using template.
|
||||
|
||||
**See:** `{project-root}/_bmad/wds/templates/1-project-brief/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:
|
||||
```markdown
|
||||
# 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-UX-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.*
|
||||
|
||||
|
||||
Reference in New Issue
Block a user