434 lines
14 KiB
Markdown
434 lines
14 KiB
Markdown
# /sdd:project-context-update
|
|
|
|
## Meta
|
|
- Version: 2.0
|
|
- Category: project-management
|
|
- Complexity: medium
|
|
- Purpose: Update project context documents with version control and consistency validation
|
|
|
|
## Definition
|
|
**Purpose**: Update technical stack, development process, coding standards, or project glossary documents while maintaining consistency across all project context files.
|
|
|
|
**Syntax**: `/sdd:project-context-update [document_type]`
|
|
|
|
## Parameters
|
|
| Parameter | Type | Required | Default | Description | Validation |
|
|
|-----------|------|----------|---------|-------------|------------|
|
|
| document_type | string | No | prompted | Which document to update | One of: technical-stack, development-process, coding-standards, project-glossary, project-brief |
|
|
|
|
## INSTRUCTION: Update Project Context Documents
|
|
|
|
### INPUTS
|
|
- document_type: Type of context document to update (optional, prompted if not provided)
|
|
- Current context documents in `/docs/project-context/`
|
|
- User-specified changes and updates
|
|
- Related documents for consistency validation
|
|
|
|
### PROCESS
|
|
|
|
#### Phase 1: Environment Verification
|
|
1. **CHECK** if `/docs/project-context/` directory exists
|
|
2. IF missing:
|
|
- SUGGEST running `/sdd:project-init` first
|
|
- EXIT with initialization guidance
|
|
3. **VERIFY** which context documents exist:
|
|
- `/docs/project-context/technical-stack.md` - Technology choices
|
|
- `/docs/project-context/coding-standards.md` - Quality rules
|
|
- `/docs/project-context/development-process.md` - Workflow definitions
|
|
- `/docs/project-context/project-glossary.md` - Domain vocabulary
|
|
- `/docs/project-context/project-brief.md` - Project overview
|
|
|
|
#### Phase 2: Document Selection
|
|
1. IF document_type provided:
|
|
- VALIDATE it matches available document types
|
|
- SET target_document to specified type
|
|
2. ELSE:
|
|
- **ASK** user which document to update:
|
|
```
|
|
Which document would you like to update?
|
|
|
|
1. technical-stack - Frameworks, languages, tools
|
|
2. development-process - Stage definitions, workflows
|
|
3. coding-standards - Naming, patterns, quality requirements
|
|
4. project-glossary - Domain terms, project vocabulary
|
|
5. project-brief - Project overview and goals
|
|
|
|
Enter number or name:
|
|
```
|
|
- CAPTURE user selection
|
|
- SET target_document based on selection
|
|
|
|
#### Phase 3: Current State Analysis
|
|
1. **READ** current content from `/docs/project-context/[target_document].md`
|
|
2. **PARSE** existing structure:
|
|
- Identify main sections
|
|
- Extract current technology choices (if technical-stack)
|
|
- Understand existing standards and patterns
|
|
- Note areas that may need updating
|
|
3. **DISPLAY** current state summary to user
|
|
4. **IDENTIFY** dependent documents that may be affected
|
|
|
|
#### Phase 4: Change Specification
|
|
1. **ASK** user what changes to make:
|
|
- Add new technology/library (requires dependent updates)
|
|
- Update existing entry (cascade changes to related standards)
|
|
- Remove deprecated item (update all references)
|
|
- Reorganize structure (maintain compatibility)
|
|
- Migrate from one technology to another (comprehensive update)
|
|
|
|
2. **GATHER** specific details:
|
|
- WHAT is being changed
|
|
- WHY the change is needed
|
|
- WHEN it should take effect
|
|
- HOW it impacts other documents
|
|
|
|
3. **ASK** for version numbers and documentation links (if technical change)
|
|
|
|
#### Phase 5: Impact Analysis
|
|
1. **ANALYZE** impact on other context documents:
|
|
|
|
IF updating technical-stack:
|
|
- CHECK if coding-standards need updates
|
|
- VERIFY development-process matches new stack
|
|
- REVIEW project-glossary for new terms
|
|
- IDENTIFY test commands that may change
|
|
|
|
IF updating coding-standards:
|
|
- VERIFY alignment with technical-stack
|
|
- CHECK if development-process reviews need updates
|
|
- NOTE impact on existing stories
|
|
|
|
IF updating development-process:
|
|
- CHECK if stages match technical-stack capabilities
|
|
- VERIFY coding-standards align with new process
|
|
- NOTE story templates that may need updates
|
|
|
|
IF updating project-glossary:
|
|
- ENSURE terms align with technical-stack
|
|
- VERIFY consistency with project-brief terminology
|
|
|
|
2. **REPORT** identified impacts to user:
|
|
```
|
|
Impact Analysis:
|
|
━━━━━━━━━━━━━━━━
|
|
Primary Change: technical-stack.md
|
|
|
|
Affected Documents:
|
|
- coding-standards.md: Test command references need update
|
|
- development-process.md: QA stage testing strategy needs alignment
|
|
|
|
Affected Stories:
|
|
- 2 stories in /development may need test updates
|
|
- 1 story in /review may need coding standard adjustments
|
|
```
|
|
|
|
#### Phase 6: Change Application
|
|
1. **CREATE** backup before modifications:
|
|
- COPY original file to `/docs/project-context/versions/`
|
|
- USE format: `[document]-backup-[timestamp].md`
|
|
- LOG backup location
|
|
|
|
2. **APPLY** changes to target document:
|
|
- UPDATE specified sections
|
|
- MAINTAIN document structure
|
|
- PRESERVE formatting and organization
|
|
- ADD timestamps or version notes if appropriate
|
|
|
|
3. **SAVE** updated document to original location
|
|
|
|
#### Phase 7: Consistency Validation
|
|
1. **VALIDATE** consistency across project-context:
|
|
- CHECK technical-stack and coding-standards align
|
|
- VERIFY development-process matches technology choices
|
|
- ENSURE project-glossary includes relevant terms
|
|
- CONFIRM project-brief reflects current state
|
|
|
|
2. **DETECT** inconsistencies or conflicts:
|
|
- Mismatched technology references
|
|
- Outdated process descriptions
|
|
- Missing terminology definitions
|
|
- Conflicting standards
|
|
|
|
3. **REPORT** validation results to user
|
|
|
|
#### Phase 8: Cascading Updates (Optional)
|
|
1. IF other documents affected:
|
|
- **ASK** user if they want to update related documents now
|
|
- FOR EACH document requiring update:
|
|
* SHOW what needs to change
|
|
* ASK for confirmation
|
|
* APPLY updates if approved
|
|
- LOG all cascading changes
|
|
|
|
2. IF user declines cascading updates:
|
|
- PROVIDE list of manual updates needed
|
|
- SUGGEST specific changes for each document
|
|
- NOTE in target document that related updates pending
|
|
|
|
#### Phase 9: Story Impact Assessment
|
|
1. **IDENTIFY** stories affected by context changes:
|
|
- SCAN `/docs/stories/development/` for impacted stories
|
|
- CHECK `/docs/stories/review/` for stories needing review updates
|
|
- NOTE `/docs/stories/qa/` stories requiring test updates
|
|
|
|
2. **SUGGEST** actions for affected stories:
|
|
- Re-run `/sdd:story-review` for stories with new standards
|
|
- Re-run `/sdd:story-qa` for stories with new test requirements
|
|
- Update story documentation with new references
|
|
|
|
#### Phase 10: Completion Summary
|
|
1. **DISPLAY** update summary:
|
|
```
|
|
✅ Context Document Updated
|
|
═══════════════════════════════════
|
|
|
|
Document: technical-stack.md
|
|
Backup: /docs/project-context/versions/technical-stack-backup-20251001-104500.md
|
|
|
|
Changes Applied:
|
|
- Added: Playwright for E2E testing
|
|
- Updated: Node.js version 18 → 20
|
|
- Removed: Deprecated library XYZ
|
|
|
|
Cascading Updates:
|
|
- coding-standards.md: Updated test naming conventions
|
|
- development-process.md: Added Playwright to QA stage
|
|
|
|
Affected Stories: 2 in development
|
|
Recommended Actions:
|
|
1. Review STORY-XXX-005 test setup
|
|
2. Update STORY-XXX-007 with new standards
|
|
```
|
|
|
|
2. **PROVIDE** next steps:
|
|
- Commands to run for impacted stories
|
|
- Documentation links for new technologies
|
|
- Timeline for completing related updates
|
|
|
|
### OUTPUTS
|
|
- Updated `/docs/project-context/[document].md` - Modified context document
|
|
- Backup `/docs/project-context/versions/[document]-backup-[timestamp].md` - Original version
|
|
- Updated related documents (if cascading updates approved)
|
|
- Impact assessment report
|
|
- Recommended actions list
|
|
|
|
### RULES
|
|
- MUST create backup before any modifications
|
|
- MUST validate consistency across all context documents
|
|
- MUST identify and report impacts on other documents
|
|
- MUST identify and report impacts on existing stories
|
|
- SHOULD offer to update related documents
|
|
- SHOULD provide specific update recommendations
|
|
- NEVER overwrite without creating backup
|
|
- ALWAYS maintain document structure and formatting
|
|
|
|
## Examples
|
|
|
|
### Example 1: Add New Testing Framework
|
|
```bash
|
|
INPUT:
|
|
/sdd:project-context-update technical-stack
|
|
|
|
INTERACTION:
|
|
→ Shows current technical-stack.md content
|
|
→ Asks: "What would you like to update?"
|
|
→ User: "Add Playwright for E2E testing"
|
|
→ Asks: "Version number?" → "1.40"
|
|
→ Asks: "Documentation link?" → "https://playwright.dev"
|
|
|
|
IMPACT ANALYSIS:
|
|
Analyzing impact...
|
|
- coding-standards.md: Test naming conventions need update
|
|
- development-process.md: QA stage needs Playwright integration
|
|
- 2 stories in /development may need test updates
|
|
|
|
OUTPUT:
|
|
✅ Context Document Updated
|
|
═══════════════════════════════════
|
|
|
|
Document: technical-stack.md
|
|
Backup: /docs/project-context/versions/technical-stack-backup-20251001-104500.md
|
|
|
|
Changes Applied:
|
|
- Added: Playwright 1.40 for E2E testing
|
|
- Updated: Browser/E2E testing section
|
|
|
|
Cascading Updates Available:
|
|
1. coding-standards.md - Add Playwright test patterns
|
|
2. development-process.md - Update QA stage with Playwright
|
|
|
|
Would you like to apply cascading updates now? [y/n]
|
|
```
|
|
|
|
### Example 2: Migrate Technology
|
|
```bash
|
|
INPUT:
|
|
/sdd:project-context-update technical-stack
|
|
|
|
INTERACTION:
|
|
→ Asks: "What would you like to update?"
|
|
→ User: "Migrate from Jest to Vitest"
|
|
|
|
IMPACT ANALYSIS:
|
|
⚠️ Major Change Detected: Test Framework Migration
|
|
|
|
Affected Documents:
|
|
- technical-stack.md: Unit testing framework
|
|
- coding-standards.md: Test file conventions, imports
|
|
- development-process.md: Test commands in all stages
|
|
- project-glossary.md: Testing terminology
|
|
|
|
Affected Stories:
|
|
- 5 stories in /development with existing tests
|
|
- 2 stories in /review with test coverage
|
|
- 3 stories in /completed may need test migration
|
|
|
|
OUTPUT:
|
|
✅ Context Document Updated
|
|
═══════════════════════════════════
|
|
|
|
Document: technical-stack.md
|
|
Backup: /docs/project-context/versions/technical-stack-backup-20251001-104530.md
|
|
|
|
Changes Applied:
|
|
- Removed: Jest (deprecated)
|
|
- Added: Vitest 1.0 (new unit testing framework)
|
|
- Updated: Test runner commands (npm test → vitest)
|
|
|
|
Cascading Updates Required:
|
|
1. coding-standards.md: Test import statements (expect from 'vitest')
|
|
2. development-process.md: Test commands in all stages
|
|
3. project-glossary.md: Update testing terminology
|
|
|
|
⚠️ IMPORTANT: Existing Stories Need Updates
|
|
- 5 stories in /development require test migration
|
|
- Consider creating migration guide story
|
|
|
|
Recommended Actions:
|
|
1. Update all context documents (run /sdd:project-context-update)
|
|
2. Create STORY-MIGRATION: Jest to Vitest migration guide
|
|
3. Re-run tests for all in-progress stories
|
|
4. Update test templates in /docs/stories/templates/
|
|
```
|
|
|
|
### Example 3: Update Coding Standards
|
|
```bash
|
|
INPUT:
|
|
/sdd:project-context-update coding-standards
|
|
|
|
INTERACTION:
|
|
→ Shows current coding-standards.md
|
|
→ Asks: "What would you like to update?"
|
|
→ User: "Change line length from 80 to 120 characters"
|
|
|
|
IMPACT ANALYSIS:
|
|
Analyzing impact...
|
|
- Technical stack: No changes needed
|
|
- Development process: No changes needed
|
|
- Existing code: May need reformatting
|
|
- Stories: 3 in /review may need re-review
|
|
|
|
OUTPUT:
|
|
✅ Context Document Updated
|
|
═══════════════════════════════════
|
|
|
|
Document: coding-standards.md
|
|
Backup: /docs/project-context/versions/coding-standards-backup-20251001-104600.md
|
|
|
|
Changes Applied:
|
|
- Updated: Line length limit 80 → 120 characters
|
|
- Updated: Prettier configuration reference
|
|
|
|
No cascading updates required.
|
|
|
|
⚠️ Code Formatting Impact:
|
|
- Existing code may need reformatting
|
|
- Run: npm run format (or equivalent)
|
|
- Consider: Re-review 3 stories in /review with new standard
|
|
|
|
Recommended Actions:
|
|
1. Run formatter across codebase
|
|
2. Re-review STORY-XXX-003, STORY-XXX-006, STORY-XXX-009
|
|
3. Update editor/IDE settings to 120 char limit
|
|
```
|
|
|
|
### Example 4: No Project Context
|
|
```bash
|
|
INPUT:
|
|
/sdd:project-context-update
|
|
|
|
OUTPUT:
|
|
⚠️ PROJECT CONTEXT NOT FOUND
|
|
|
|
The /docs/project-context/ directory does not exist.
|
|
|
|
To set up the story-driven development system, run:
|
|
→ /sdd:project-init
|
|
|
|
This will create:
|
|
- Project context directory
|
|
- All context documents
|
|
- Document templates
|
|
```
|
|
|
|
## Edge Cases
|
|
|
|
### Document Doesn't Exist
|
|
- DETECT missing document
|
|
- OFFER to create it with standard template
|
|
- IF user confirms, create document and continue
|
|
- ELSE suggest running `/sdd:project-init`
|
|
|
|
### No Changes Specified
|
|
- IF user can't specify changes clearly
|
|
- OFFER examples of common updates
|
|
- PROVIDE guided questions
|
|
- ALLOW user to cancel if not ready
|
|
|
|
### Conflicting Updates
|
|
- DETECT conflicts between updates
|
|
- EXPLAIN the conflict to user
|
|
- SUGGEST resolution approaches
|
|
- REQUIRE user decision before proceeding
|
|
|
|
### Large Cascading Impact
|
|
- IF changes affect many documents/stories
|
|
- WARN user about scope of impact
|
|
- SUGGEST breaking into smaller updates
|
|
- PROVIDE option to review impact before applying
|
|
|
|
## Error Handling
|
|
- **Missing /docs/project-context/**: Suggest `/sdd:project-init` with clear instructions
|
|
- **Document not found**: Offer to create with template or abort
|
|
- **Backup creation fails**: MUST NOT proceed with updates, report error
|
|
- **Permission errors**: Report specific file with access issue
|
|
- **Validation failures**: Show inconsistencies, suggest fixes, don't force update
|
|
|
|
## Performance Considerations
|
|
- Document reads are fast (< 100ms)
|
|
- Impact analysis scales with document count (typically < 1s)
|
|
- Backup creation is quick (< 50ms per file)
|
|
- Story scanning may take longer (100+ stories: ~2-3s)
|
|
|
|
## Security Considerations
|
|
- Verify write permissions before modifications
|
|
- Validate all file paths stay within project
|
|
- Create backups before any destructive operations
|
|
- Don't expose sensitive configuration data
|
|
|
|
## Related Commands
|
|
- `/sdd:project-init` - Initialize project structure if missing
|
|
- `/sdd:project-brief` - Update high-level project documentation
|
|
- `/sdd:story-review` - Re-review stories with new standards
|
|
- `/sdd:story-qa` - Re-test stories with new requirements
|
|
- `/sdd:project-status` - View current project state
|
|
|
|
## Constraints
|
|
- ⚠️ MUST create backup before any modification
|
|
- ✅ MUST validate consistency across context documents
|
|
- ✅ MUST identify impact on other documents and stories
|
|
- 📋 SHOULD offer to apply cascading updates
|
|
- 🔄 SHOULD provide specific recommendations
|
|
- ⚡ MUST complete analysis in < 5 seconds
|
|
- 💾 NEVER overwrite without backup
|