/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

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

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

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

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