zhongwei/gh-ninthspace-claude-code-marketplace-sdd

Files

Zhongwei Li d97a70be33 Initial commit

2025-11-30 08:44:27 +08:00

14 KiB

Raw Permalink Blame History

/sdd:project-context-update

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

CHECK if /docs/project-context/ directory exists
IF missing:
- SUGGEST running /sdd:project-init first
- EXIT with initialization guidance
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

IF document_type provided:
- VALIDATE it matches available document types
- SET target_document to specified type

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

READ current content from /docs/project-context/[target_document].md
PARSE existing structure:
- Identify main sections
- Extract current technology choices (if technical-stack)
- Understand existing standards and patterns
- Note areas that may need updating
DISPLAY current state summary to user
IDENTIFY dependent documents that may be affected

Phase 4: Change Specification

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)
GATHER specific details:
- WHAT is being changed
- WHY the change is needed
- WHEN it should take effect
- HOW it impacts other documents
ASK for version numbers and documentation links (if technical change)

Phase 5: Impact Analysis

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

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

CREATE backup before modifications:
- COPY original file to /docs/project-context/versions/
- USE format: [document]-backup-[timestamp].md
- LOG backup location
APPLY changes to target document:
- UPDATE specified sections
- MAINTAIN document structure
- PRESERVE formatting and organization
- ADD timestamps or version notes if appropriate
SAVE updated document to original location

Phase 7: Consistency Validation

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
DETECT inconsistencies or conflicts:
- Mismatched technology references
- Outdated process descriptions
- Missing terminology definitions
- Conflicting standards
REPORT validation results to user

Phase 8: Cascading Updates (Optional)

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
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

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
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

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

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

/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

14 KiB Raw Permalink Blame History