appiq-solution 1.4.3 → 1.4.4

package/bmad-core/tasks/create-flutter-story.md

@@ -0,0 +1,197 @@
+# Create Flutter Story Task
+
+## Overview
+This task creates a detailed Flutter development story following Clean Architecture principles with feature-based organization. The story will include all three layers (data/domain/presentation) and comprehensive testing requirements.
+
+## Prerequisites
+- Flutter PRD document available
+- Flutter architecture document (if applicable)
+- Feature requirements clearly defined
+- UI/UX specifications available
+
+## Task Execution
+
+### Step 1: Gather Requirements
+**Action:** Collect and analyze story requirements
+**Process:**
+1. Read Flutter PRD or feature requirements
+2. Review UI/UX specifications if available
+3. Understand user needs and business value
+4. Identify technical constraints and dependencies
+5. Determine story scope and complexity
+
+**Deliverable:** Clear understanding of feature requirements
+
+### Step 2: Define User Story
+**Action:** Create user story following standard format
+**Process:**
+1. Identify the user persona and role
+2. Define the specific functionality/goal
+3. Articulate the business value/benefit
+4. Add mobile-specific context and usage scenarios
+5. Consider offline/online behavior requirements
+
+**Template:**
+```
+As a [type of user]
+I want [goal/functionality]
+So that [benefit/value]
+
+Mobile Context:
+- Device usage scenario
+- User interaction patterns
+- Performance expectations
+```
+
+### Step 3: Create Acceptance Criteria
+**Action:** Define comprehensive, testable acceptance criteria
+**Process:**
+1. **Functional Criteria:** Define what the feature must do
+2. **UI/UX Criteria:** Material Design 3, responsive design, accessibility
+3. **Technical Criteria:** Clean Architecture, state management, error handling
+4. **Performance Criteria:** Loading times, animations, memory usage
+
+**Quality Check:** Each criterion must be:
+- Specific and measurable
+- Testable with clear pass/fail conditions
+- Aligned with user value and business goals
+
+### Step 4: Break Down Flutter Implementation Tasks
+**Action:** Organize tasks by Flutter Clean Architecture layers
+**Process:**
+
+#### A. Presentation Layer Tasks
+1. **UI Implementation:**
+   - Create feature pages/screens with Material 3 design
+   - Implement custom widgets and components  
+   - Set up responsive layouts for phone/tablet
+   - Add animations and micro-interactions
+   - Implement accessibility features
+
+2. **State Management (Cubit):**
+   - Create Cubit class with business logic coordination
+   - Define State classes with Equatable
+   - Implement state transitions and error handling
+   - Connect UI to Cubit with BlocBuilder/BlocListener
+
+3. **Navigation & Routing:**
+   - Define routes and navigation paths
+   - Implement deep linking (if required)
+   - Add navigation transitions
+
+#### B. Domain Layer Tasks
+1. **Business Entities:**
+   - Create entity classes with Equatable
+   - Define entity relationships and properties
+   - Add entity validation rules
+
+2. **Use Cases:**
+   - Implement use case classes with @injectable
+   - Add business logic and validation
+   - Define Either<Failure, Success> return types
+
+3. **Repository Interfaces:**
+   - Define repository abstract classes
+   - Specify method signatures and return types
+
+#### C. Data Layer Tasks
+1. **Data Models:**
+   - Create model classes with @freezed annotation
+   - Add JSON serialization
+   - Implement model to entity conversion methods
+
+2. **Repository Implementations:**
+   - Implement concrete repository classes
+   - Add error handling and data transformation
+
+3. **Data Sources:**
+   - Create remote data source for API calls
+   - Implement local data source for caching
+   - Add offline-first functionality (if required)
+
+#### D. Cross-Cutting Tasks
+1. **Localization & Theming:**
+   - Add all text content to ARB files
+   - Implement RTL support
+   - Verify dark/light theme compatibility
+
+2. **Testing:**
+   - Unit tests for domain layer
+   - Unit tests for data layer
+   - Widget tests for UI components
+   - Cubit/state management tests
+   - Integration tests for user flows
+
+### Step 5: Add Technical Implementation Details
+**Action:** Provide technical guidance for developers
+**Process:**
+1. List required Flutter dependencies
+2. Define file structure following feature-based architecture
+3. Specify key implementation patterns
+4. Include performance considerations
+5. Add security requirements (if applicable)
+
+### Step 6: Define Testing Requirements
+**Action:** Create comprehensive testing strategy
+**Process:**
+1. **Unit Tests:** Domain and data layer testing with mocks
+2. **Widget Tests:** UI component testing in isolation
+3. **Cubit Tests:** State management testing with bloc_test
+4. **Integration Tests:** End-to-end user flow testing
+5. **Accessibility Tests:** Screen reader and semantic testing
+
+**Coverage Target:** Minimum 80% code coverage, 100% for business logic
+
+### Step 7: Add Development Notes
+**Action:** Include additional guidance and considerations
+**Process:**
+1. Performance optimization tips
+2. Accessibility implementation guidelines
+3. Localization best practices
+4. Code quality standards
+5. Common pitfalls and solutions
+
+### Step 8: Create Definition of Done
+**Action:** Define clear completion criteria
+**Process:**
+1. **Implementation Complete:** All tasks and layers implemented
+2. **Code Quality:** Follows Flutter best practices and standards
+3. **Testing Complete:** All tests written and passing
+4. **Performance Verified:** Meets performance benchmarks
+5. **Documentation:** Code documented and file list updated
+6. **Review Process:** Code review, design review, QA testing completed
+
+## Template Usage
+**Template:** Use `flutter-story-tmpl.yaml` for consistent story structure
+
+## Quality Validation
+Before marking story as complete, verify:
+- [ ] Story follows standard user story format
+- [ ] Acceptance criteria are specific and testable
+- [ ] Tasks cover all Flutter architecture layers
+- [ ] Technical details provide clear implementation guidance  
+- [ ] Testing requirements are comprehensive
+- [ ] Performance and accessibility requirements included
+- [ ] Localization requirements specified
+- [ ] Definition of done is complete and measurable
+
+## Handoff Process
+1. Review story with Product Owner for business value alignment
+2. Review with Tech Lead for technical feasibility
+3. Estimate story points with development team
+4. Ensure all dependencies are identified and available
+5. Confirm story is ready for development sprint
+
+## Success Criteria
+- Story provides complete implementation guidance for developers
+- All acceptance criteria are testable and measurable
+- Technical approach follows Flutter Clean Architecture principles
+- Story scope is appropriate for single sprint completion
+- Dependencies and integration points are clearly identified
+
+## Notes
+- Keep stories focused on single feature or user flow
+- Ensure story can be completed within one sprint (usually 1-2 weeks)
+- Consider breaking large features into multiple stories
+- Always include mobile-specific considerations (performance, battery, offline)
+- Maintain consistency with existing codebase patterns and standards

package/bmad-core/tasks/create-next-story.md

@@ -0,0 +1,112 @@
+# Create Next Story Task
+
+## Purpose
+
+To identify the next logical story based on project progress and epic definitions, and then to prepare a comprehensive, self-contained, and actionable story file using the `Story Template`. This task ensures the story is enriched with all necessary technical context, requirements, and acceptance criteria, making it ready for efficient implementation by a Developer Agent with minimal need for additional research or finding its own context.
+
+## SEQUENTIAL Task Execution (Do not proceed until current Task is complete)
+
+### 0. Load Core Configuration and Check Workflow
+
+- Load `{root}/core-config.yaml` from the project root
+- If the file does not exist, HALT and inform the user: "core-config.yaml not found. This file is required for story creation. You can either: 1) Copy it from GITHUB bmad-core/core-config.yaml and configure it for your project OR 2) Run the BMad installer against your project to upgrade and add the file automatically. Please add and configure core-config.yaml before proceeding."
+- Extract key configurations: `devStoryLocation`, `prd.*`, `architecture.*`, `workflow.*`
+
+### 1. Identify Next Story for Preparation
+
+#### 1.1 Locate Epic Files and Review Existing Stories
+
+- Based on `prdSharded` from config, locate epic files (sharded location/pattern or monolithic PRD sections)
+- If `devStoryLocation` has story files, load the highest `{epicNum}.{storyNum}.story.md` file
+- **If highest story exists:**
+  - Verify status is 'Done'. If not, alert user: "ALERT: Found incomplete story! File: {lastEpicNum}.{lastStoryNum}.story.md Status: [current status] You should fix this story first, but would you like to accept risk & override to create the next story in draft?"
+  - If proceeding, select next sequential story in the current epic
+  - If epic is complete, prompt user: "Epic {epicNum} Complete: All stories in Epic {epicNum} have been completed. Would you like to: 1) Begin Epic {epicNum + 1} with story 1 2) Select a specific story to work on 3) Cancel story creation"
+  - **CRITICAL**: NEVER automatically skip to another epic. User MUST explicitly instruct which story to create.
+- **If no story files exist:** The next story is ALWAYS 1.1 (first story of first epic)
+- Announce the identified story to the user: "Identified next story for preparation: {epicNum}.{storyNum} - {Story Title}"
+
+### 2. Gather Story Requirements and Previous Story Context
+
+- Extract story requirements from the identified epic file
+- If previous story exists, review Dev Agent Record sections for:
+  - Completion Notes and Debug Log References
+  - Implementation deviations and technical decisions
+  - Challenges encountered and lessons learned
+- Extract relevant insights that inform the current story's preparation
+
+### 3. Gather Architecture Context
+
+#### 3.1 Determine Architecture Reading Strategy
+
+- **If `architectureVersion: >= v4` and `architectureSharded: true`**: Read `{architectureShardedLocation}/index.md` then follow structured reading order below
+- **Else**: Use monolithic `architectureFile` for similar sections
+
+#### 3.2 Read Architecture Documents Based on Story Type
+
+**For ALL Stories:** tech-stack.md, unified-project-structure.md, coding-standards.md, testing-strategy.md
+
+**For Backend/API Stories, additionally:** data-models.md, database-schema.md, backend-architecture.md, rest-api-spec.md, external-apis.md
+
+**For Frontend/UI Stories, additionally:** frontend-architecture.md, components.md, core-workflows.md, data-models.md
+
+**For Full-Stack Stories:** Read both Backend and Frontend sections above
+
+#### 3.3 Extract Story-Specific Technical Details
+
+Extract ONLY information directly relevant to implementing the current story. Do NOT invent new libraries, patterns, or standards not in the source documents.
+
+Extract:
+
+- Specific data models, schemas, or structures the story will use
+- API endpoints the story must implement or consume
+- Component specifications for UI elements in the story
+- File paths and naming conventions for new code
+- Testing requirements specific to the story's features
+- Security or performance considerations affecting the story
+
+ALWAYS cite source documents: `[Source: architecture/{filename}.md#{section}]`
+
+### 4. Verify Project Structure Alignment
+
+- Cross-reference story requirements with Project Structure Guide from `docs/architecture/unified-project-structure.md`
+- Ensure file paths, component locations, or module names align with defined structures
+- Document any structural conflicts in "Project Structure Notes" section within the story draft
+
+### 5. Populate Story Template with Full Context
+
+- Create new story file: `{devStoryLocation}/{epicNum}.{storyNum}.story.md` using Story Template
+- Fill in basic story information: Title, Status (Draft), Story statement, Acceptance Criteria from Epic
+- **`Dev Notes` section (CRITICAL):**
+  - CRITICAL: This section MUST contain ONLY information extracted from architecture documents. NEVER invent or assume technical details.
+  - Include ALL relevant technical details from Steps 2-3, organized by category:
+    - **Previous Story Insights**: Key learnings from previous story
+    - **Data Models**: Specific schemas, validation rules, relationships [with source references]
+    - **API Specifications**: Endpoint details, request/response formats, auth requirements [with source references]
+    - **Component Specifications**: UI component details, props, state management [with source references]
+    - **File Locations**: Exact paths where new code should be created based on project structure
+    - **Testing Requirements**: Specific test cases or strategies from testing-strategy.md
+    - **Technical Constraints**: Version requirements, performance considerations, security rules
+  - Every technical detail MUST include its source reference: `[Source: architecture/{filename}.md#{section}]`
+  - If information for a category is not found in the architecture docs, explicitly state: "No specific guidance found in architecture docs"
+- **`Tasks / Subtasks` section:**
+  - Generate detailed, sequential list of technical tasks based ONLY on: Epic Requirements, Story AC, Reviewed Architecture Information
+  - Each task must reference relevant architecture documentation
+  - Include unit testing as explicit subtasks based on the Testing Strategy
+  - Link tasks to ACs where applicable (e.g., `Task 1 (AC: 1, 3)`)
+- Add notes on project structure alignment or discrepancies found in Step 4
+
+### 6. Story Draft Completion and Review
+
+- Review all sections for completeness and accuracy
+- Verify all source references are included for technical details
+- Ensure tasks align with both epic requirements and architecture constraints
+- Update status to "Draft" and save the story file
+- Execute `{root}/tasks/execute-checklist` `{root}/checklists/story-draft-checklist`
+- Provide summary to user including:
+  - Story created: `{devStoryLocation}/{epicNum}.{storyNum}.story.md`
+  - Status: Draft
+  - Key technical components included from architecture docs
+  - Any deviations or conflicts noted between epic and architecture
+  - Checklist Results
+  - Next steps: For Complex stories, suggest the user carefully review the story draft and also optionally have the PO run the task `{root}/tasks/validate-next-story`

package/bmad-core/tasks/document-project.md

@@ -0,0 +1,341 @@
+# Document an Existing Project
+
+## Purpose
+
+Generate comprehensive documentation for existing projects optimized for AI development agents. This task creates structured reference materials that enable AI agents to understand project context, conventions, and patterns for effective contribution to any codebase.
+
+## Task Instructions
+
+### 1. Initial Project Analysis
+
+**CRITICAL:** First, check if a PRD or requirements document exists in context. If yes, use it to focus your documentation efforts on relevant areas only.
+
+**IF PRD EXISTS**:
+
+- Review the PRD to understand what enhancement/feature is planned
+- Identify which modules, services, or areas will be affected
+- Focus documentation ONLY on these relevant areas
+- Skip unrelated parts of the codebase to keep docs lean
+
+**IF NO PRD EXISTS**:
+Ask the user:
+
+"I notice you haven't provided a PRD or requirements document. To create more focused and useful documentation, I recommend one of these options:
+
+1. **Create a PRD first** - Would you like me to help create a brownfield PRD before documenting? This helps focus documentation on relevant areas.
+
+2. **Provide existing requirements** - Do you have a requirements document, epic, or feature description you can share?
+
+3. **Describe the focus** - Can you briefly describe what enhancement or feature you're planning? For example:
+   - 'Adding payment processing to the user service'
+   - 'Refactoring the authentication module'
+   - 'Integrating with a new third-party API'
+
+4. **Document everything** - Or should I proceed with comprehensive documentation of the entire codebase? (Note: This may create excessive documentation for large projects)
+
+Please let me know your preference, or I can proceed with full documentation if you prefer."
+
+Based on their response:
+
+- If they choose option 1-3: Use that context to focus documentation
+- If they choose option 4 or decline: Proceed with comprehensive analysis below
+
+Begin by conducting analysis of the existing project. Use available tools to:
+
+1. **Project Structure Discovery**: Examine the root directory structure, identify main folders, and understand the overall organization
+2. **Technology Stack Identification**: Look for package.json, requirements.txt, Cargo.toml, pom.xml, etc. to identify languages, frameworks, and dependencies
+3. **Build System Analysis**: Find build scripts, CI/CD configurations, and development commands
+4. **Existing Documentation Review**: Check for README files, docs folders, and any existing documentation
+5. **Code Pattern Analysis**: Sample key files to understand coding patterns, naming conventions, and architectural approaches
+
+Ask the user these elicitation questions to better understand their needs:
+
+- What is the primary purpose of this project?
+- Are there any specific areas of the codebase that are particularly complex or important for agents to understand?
+- What types of tasks do you expect AI agents to perform on this project? (e.g., bug fixes, feature additions, refactoring, testing)
+- Are there any existing documentation standards or formats you prefer?
+- What level of technical detail should the documentation target? (junior developers, senior developers, mixed team)
+- Is there a specific feature or enhancement you're planning? (This helps focus documentation)
+
+### 2. Deep Codebase Analysis
+
+CRITICAL: Before generating documentation, conduct extensive analysis of the existing codebase:
+
+1. **Explore Key Areas**:
+   - Entry points (main files, index files, app initializers)
+   - Configuration files and environment setup
+   - Package dependencies and versions
+   - Build and deployment configurations
+   - Test suites and coverage
+
+2. **Ask Clarifying Questions**:
+   - "I see you're using [technology X]. Are there any custom patterns or conventions I should document?"
+   - "What are the most critical/complex parts of this system that developers struggle with?"
+   - "Are there any undocumented 'tribal knowledge' areas I should capture?"
+   - "What technical debt or known issues should I document?"
+   - "Which parts of the codebase change most frequently?"
+
+3. **Map the Reality**:
+   - Identify ACTUAL patterns used (not theoretical best practices)
+   - Find where key business logic lives
+   - Locate integration points and external dependencies
+   - Document workarounds and technical debt
+   - Note areas that differ from standard patterns
+
+**IF PRD PROVIDED**: Also analyze what would need to change for the enhancement
+
+### 3. Core Documentation Generation
+
+[[LLM: Generate a comprehensive BROWNFIELD architecture document that reflects the ACTUAL state of the codebase.
+
+**CRITICAL**: This is NOT an aspirational architecture document. Document what EXISTS, including:
+
+- Technical debt and workarounds
+- Inconsistent patterns between different parts
+- Legacy code that can't be changed
+- Integration constraints
+- Performance bottlenecks
+
+**Document Structure**:
+
+# [Project Name] Brownfield Architecture Document
+
+## Introduction
+
+This document captures the CURRENT STATE of the [Project Name] codebase, including technical debt, workarounds, and real-world patterns. It serves as a reference for AI agents working on enhancements.
+
+### Document Scope
+
+[If PRD provided: "Focused on areas relevant to: {enhancement description}"]
+[If no PRD: "Comprehensive documentation of entire system"]
+
+### Change Log
+
+| Date | Version | Description | Author |
+|------|---------|-------------|--------|
+| [Date] | 1.0 | Initial brownfield analysis | [Analyst] |
+
+## Quick Reference - Key Files and Entry Points
+
+### Critical Files for Understanding the System
+
+- **Main Entry**: `src/index.js` (or actual entry point)
+- **Configuration**: `config/app.config.js`, `.env.example`
+- **Core Business Logic**: `src/services/`, `src/domain/`
+- **API Definitions**: `src/routes/` or link to OpenAPI spec
+- **Database Models**: `src/models/` or link to schema files
+- **Key Algorithms**: [List specific files with complex logic]
+
+### If PRD Provided - Enhancement Impact Areas
+
+[Highlight which files/modules will be affected by the planned enhancement]
+
+## High Level Architecture
+
+### Technical Summary
+
+### Actual Tech Stack (from package.json/requirements.txt)
+
+| Category | Technology | Version | Notes |
+|----------|------------|---------|--------|
+| Runtime | Node.js | 16.x | [Any constraints] |
+| Framework | Express | 4.18.2 | [Custom middleware?] |
+| Database | PostgreSQL | 13 | [Connection pooling setup] |
+
+etc...
+
+### Repository Structure Reality Check
+
+- Type: [Monorepo/Polyrepo/Hybrid]
+- Package Manager: [npm/yarn/pnpm]
+- Notable: [Any unusual structure decisions]
+
+## Source Tree and Module Organization
+
+### Project Structure (Actual)
+
+```text
+project-root/
+├── src/
+│   ├── controllers/     # HTTP request handlers
+│   ├── services/        # Business logic (NOTE: inconsistent patterns between user and payment services)
+│   ├── models/          # Database models (Sequelize)
+│   ├── utils/           # Mixed bag - needs refactoring
+│   └── legacy/          # DO NOT MODIFY - old payment system still in use
+├── tests/               # Jest tests (60% coverage)
+├── scripts/             # Build and deployment scripts
+└── config/              # Environment configs
+```
+
+### Key Modules and Their Purpose
+
+- **User Management**: `src/services/userService.js` - Handles all user operations
+- **Authentication**: `src/middleware/auth.js` - JWT-based, custom implementation
+- **Payment Processing**: `src/legacy/payment.js` - CRITICAL: Do not refactor, tightly coupled
+- **[List other key modules with their actual files]**
+
+## Data Models and APIs
+
+### Data Models
+
+Instead of duplicating, reference actual model files:
+- **User Model**: See `src/models/User.js`
+- **Order Model**: See `src/models/Order.js`
+- **Related Types**: TypeScript definitions in `src/types/`
+
+### API Specifications
+
+- **OpenAPI Spec**: `docs/api/openapi.yaml` (if exists)
+- **Postman Collection**: `docs/api/postman-collection.json`
+- **Manual Endpoints**: [List any undocumented endpoints discovered]
+
+## Technical Debt and Known Issues
+
+### Critical Technical Debt
+
+1. **Payment Service**: Legacy code in `src/legacy/payment.js` - tightly coupled, no tests
+2. **User Service**: Different pattern than other services, uses callbacks instead of promises
+3. **Database Migrations**: Manually tracked, no proper migration tool
+4. **[Other significant debt]**
+
+### Workarounds and Gotchas
+
+- **Environment Variables**: Must set `NODE_ENV=production` even for staging (historical reason)
+- **Database Connections**: Connection pool hardcoded to 10, changing breaks payment service
+- **[Other workarounds developers need to know]**
+
+## Integration Points and External Dependencies
+
+### External Services
+
+| Service | Purpose | Integration Type | Key Files |
+|---------|---------|------------------|-----------|
+| Stripe | Payments | REST API | `src/integrations/stripe/` |
+| SendGrid | Emails | SDK | `src/services/emailService.js` |
+
+etc...
+
+### Internal Integration Points
+
+- **Frontend Communication**: REST API on port 3000, expects specific headers
+- **Background Jobs**: Redis queue, see `src/workers/`
+- **[Other integrations]**
+
+## Development and Deployment
+
+### Local Development Setup
+
+1. Actual steps that work (not ideal steps)
+2. Known issues with setup
+3. Required environment variables (see `.env.example`)
+
+### Build and Deployment Process
+
+- **Build Command**: `npm run build` (webpack config in `webpack.config.js`)
+- **Deployment**: Manual deployment via `scripts/deploy.sh`
+- **Environments**: Dev, Staging, Prod (see `config/environments/`)
+
+## Testing Reality
+
+### Current Test Coverage
+
+- Unit Tests: 60% coverage (Jest)
+- Integration Tests: Minimal, in `tests/integration/`
+- E2E Tests: None
+- Manual Testing: Primary QA method
+
+### Running Tests
+
+```bash
+npm test           # Runs unit tests
+npm run test:integration  # Runs integration tests (requires local DB)
+```
+
+## If Enhancement PRD Provided - Impact Analysis
+
+### Files That Will Need Modification
+
+Based on the enhancement requirements, these files will be affected:
+- `src/services/userService.js` - Add new user fields
+- `src/models/User.js` - Update schema
+- `src/routes/userRoutes.js` - New endpoints
+- [etc...]
+
+### New Files/Modules Needed
+
+- `src/services/newFeatureService.js` - New business logic
+- `src/models/NewFeature.js` - New data model
+- [etc...]
+
+### Integration Considerations
+
+- Will need to integrate with existing auth middleware
+- Must follow existing response format in `src/utils/responseFormatter.js`
+- [Other integration points]
+
+## Appendix - Useful Commands and Scripts
+
+### Frequently Used Commands
+
+```bash
+npm run dev         # Start development server
+npm run build       # Production build
+npm run migrate     # Run database migrations
+npm run seed        # Seed test data
+```
+
+### Debugging and Troubleshooting
+
+- **Logs**: Check `logs/app.log` for application logs
+- **Debug Mode**: Set `DEBUG=app:*` for verbose logging
+- **Common Issues**: See `docs/troubleshooting.md`]]
+
+### 4. Document Delivery
+
+1. **In Web UI (Gemini, ChatGPT, Claude)**:
+   - Present the entire document in one response (or multiple if too long)
+   - Tell user to copy and save as `docs/brownfield-architecture.md` or `docs/project-architecture.md`
+   - Mention it can be sharded later in IDE if needed
+
+2. **In IDE Environment**:
+   - Create the document as `docs/brownfield-architecture.md`
+   - Inform user this single document contains all architectural information
+   - Can be sharded later using PO agent if desired
+
+The document should be comprehensive enough that future agents can understand:
+
+- The actual state of the system (not idealized)
+- Where to find key files and logic
+- What technical debt exists
+- What constraints must be respected
+- If PRD provided: What needs to change for the enhancement]]
+
+### 5. Quality Assurance
+
+CRITICAL: Before finalizing the document:
+
+1. **Accuracy Check**: Verify all technical details match the actual codebase
+2. **Completeness Review**: Ensure all major system components are documented
+3. **Focus Validation**: If user provided scope, verify relevant areas are emphasized
+4. **Clarity Assessment**: Check that explanations are clear for AI agents
+5. **Navigation**: Ensure document has clear section structure for easy reference
+
+Apply the advanced elicitation task after major sections to refine based on user feedback.
+
+## Success Criteria
+
+- Single comprehensive brownfield architecture document created
+- Document reflects REALITY including technical debt and workarounds
+- Key files and modules are referenced with actual paths
+- Models/APIs reference source files rather than duplicating content
+- If PRD provided: Clear impact analysis showing what needs to change
+- Document enables AI agents to navigate and understand the actual codebase
+- Technical constraints and "gotchas" are clearly documented
+
+## Notes
+
+- This task creates ONE document that captures the TRUE state of the system
+- References actual files rather than duplicating content when possible
+- Documents technical debt, workarounds, and constraints honestly
+- For brownfield projects with PRD: Provides clear enhancement impact analysis
+- The goal is PRACTICAL documentation for AI agents doing real work