Initial commit

skills/references/workflows.md

@@ -0,0 +1,156 @@
+# Architecture Documentation Workflows
+
+## Table of Contents
+- Interview Workflow for New Projects
+- Interview Workflow for Existing Systems
+- Documentation Generation Process
+- Update and Maintenance Workflow
+
+## Interview Workflow for New Projects
+
+Gather information through these questions in order:
+
+### Phase 1: Project Context (2-3 questions)
+1. **Project basics**: Name, purpose, target users
+2. **Timeline**: Launch date, current phase (planning/development/production)
+3. **Team**: Size, composition, experience level
+
+### Phase 2: Technical Stack (2-4 questions)
+1. **Backend**: Primary language and framework (e.g., "Node.js with Express" or "Python with Django")
+2. **Frontend**: Framework or approach (e.g., "React SPA" or "Server-rendered with templates")
+3. **Database**: Type and name (e.g., "PostgreSQL" or "MongoDB")
+4. **Infrastructure**: Cloud provider or hosting (e.g., "AWS" or "On-premise")
+
+### Phase 3: Architecture Pattern (1-2 questions)
+1. **Pattern**: Monolith, microservices, serverless, or hybrid
+2. **Rationale**: Why this pattern? (helps understand constraints)
+
+### Phase 4: Components (2-4 questions based on pattern)
+
+For Monolith:
+- Main modules or features
+- Background jobs or scheduled tasks
+- Static asset handling
+
+For Microservices:
+- List of services (name and responsibility)
+- How services communicate (REST, gRPC, message queue)
+- Shared components (API gateway, service mesh)
+
+For Serverless:
+- Functions and their triggers
+- State management approach
+- Event sources
+
+### Phase 5: Data and Integrations (1-3 questions)
+1. **Additional data stores**: Cache, search engine, file storage
+2. **External services**: Payment, email, analytics, etc.
+3. **APIs**: Third-party APIs being consumed
+
+### Phase 6: Operations (1-2 questions)
+1. **Deployment**: Manual, CI/CD, orchestration
+2. **Monitoring**: Logging, metrics, alerting setup
+
+## Interview Workflow for Existing Systems
+
+For systems already built, adjust approach:
+
+### Quick Assessment
+1. **Documentation exists?** If yes, review it first
+2. **Codebase access?** If yes, analyze structure
+3. **Team knowledge?** Interview developers
+
+### Targeted Questions
+1. What's changed since last documentation?
+2. What's causing confusion for new developers?
+3. What's undocumented or poorly documented?
+4. Are there any planned changes?
+
+### Validation Approach
+- Cross-reference answers with code
+- Identify discrepancies between docs and reality
+- Highlight areas needing attention
+
+## Documentation Generation Process
+
+### Step 1: Select Template
+Choose based on architecture pattern:
+- `assets/ARCHITECTURE.md` for general/unknown
+- `assets/ARCHITECTURE-microservices.md` for microservices
+- `assets/ARCHITECTURE-monolith.md` for monoliths
+
+### Step 2: Generate System Diagram
+Use `scripts/generate_diagram.py` based on pattern:
+- Monolith: Use "layered" type
+- Microservices: Use "flow" or "c4" type
+- Simple systems: Use "simple" type
+
+### Step 3: Fill Template Sections
+Populate in this order:
+1. Project Identification (Section 10) - establishes context
+2. Project Structure (Section 1) - concrete foundation
+3. System Diagram (Section 2) - using generated diagram
+4. Core Components (Section 3) - from interview data
+5. Data Stores (Section 4) - databases and caches
+6. External Integrations (Section 5) - third-party services
+7. Deployment & Infrastructure (Section 6) - ops details
+8. Security Considerations (Section 7) - auth, encryption
+9. Development & Testing (Section 8) - dev environment
+10. Future Considerations (Section 9) - roadmap items
+11. Glossary (Section 11) - domain-specific terms
+
+### Step 4: Enhance with Technology Specifics
+Load relevant reference and apply patterns:
+- Node.js: See references/nodejs.md
+- Python: See references/python.md
+- Java: See references/java.md
+
+### Step 5: Validate
+Run validation script:
+```bash
+python scripts/validate_architecture.py ARCHITECTURE.md
+```
+
+Address any issues or warnings.
+
+## Update and Maintenance Workflow
+
+### For Incremental Updates
+1. Identify changed components
+2. Update affected sections only
+3. Update "Date of Last Update" in Section 10
+4. Add brief note in Future Considerations if major change
+
+### For Major Updates
+1. Re-interview on changed areas
+2. Regenerate system diagram if structure changed
+3. Update multiple sections as needed
+4. Consider adding version notes
+
+### Best Practices
+- Keep updates small and frequent
+- Document changes when they happen
+- Review quarterly even if no changes
+- Archive old versions if major restructure
+
+## Tips for Effective Interviews
+
+### Keep Questions Focused
+- Ask one thing at a time
+- Avoid overwhelming with options
+- Build on previous answers
+
+### Adapt Based on Responses
+- If user is technical, use technical terms
+- If user is non-technical, simplify language
+- Skip redundant questions
+
+### Handle Uncertainty
+- If user unsure, offer to add placeholder
+- Suggest reasonable defaults
+- Mark uncertain items for review
+
+### Validate Understanding
+- Summarize what you heard
+- Confirm critical details
+- Check for consistency