zhongwei/gh-ninthspace-claude-code-marketplace-sdd
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
d97a70be331ab765e3a939a4d772797f37f783bc
gh-ninthspace-claude-code-m…/commands/project-context-update.md
Zhongwei Li d97a70be33 Initial commit
2025-11-30 08:44:27 +08:00

14 KiB
Raw Blame History

/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
Reference in New Issue View Git Blame Copy Permalink