Update Specification

Update Specification

update-specification skill for programming & development

Category: development Source: github

An AI skill that revises and maintains software specification documents based on implementation feedback, requirement changes, and stakeholder input, ensuring that project specifications remain accurate and aligned with the actual system being built.

What Is This?

Overview

This skill updates software specification documents by incorporating changes from multiple sources: implementation discoveries, new business requirements, technical constraints, and stakeholder feedback. It tracks which sections need revision, identifies conflicts between new information and existing specs, updates related sections for consistency, and generates change summaries for stakeholder review. The result is a living specification that accurately describes the system.

Who Should Use This

Ideal for product managers maintaining requirement documents, tech leads keeping technical specs current, and teams practicing iterative development where specifications evolve alongside implementation.

Why Use It?

Problems It Solves

Specification documents are written early in a project but rarely updated as development reveals new realities. Implementation deviates from specs due to technical constraints, requirements shift based on user feedback, and scope adjustments go undocumented. Stale specs mislead new team members, cause incorrect testing, and create confusion during audits.

Core Highlights

  • Change Integration merges updates from multiple sources into the spec
  • Conflict Detection identifies contradictions between new and existing content
  • Cascade Updates revises related sections when one section changes
  • Change Tracking maintains a log of all modifications with reasons
  • Stakeholder Summaries generates concise change reports for review

How to Use It?

Basic Usage

Provide the current spec and changes to incorporate, and receive an updated document.

## Specification Update: User Authentication

### Changes Applied:

1. Section 3.2 - Login Flow
   - UPDATED: Added OAuth2 provider support (Google, GitHub)
   - Reason: Business requirement from Q1 planning
   
2. Section 3.4 - Session Management  
   - UPDATED: Session timeout changed from 24h to 8h
   - Reason: Security audit recommendation
   
3. Section 4.1 - API Endpoints
   - ADDED: POST /auth/oauth/callback endpoint
   - Reason: Required for OAuth2 flow added in 3.2

### Conflicts Found:
   - Section 3.2 states "email/password only" but now includes OAuth2
   - Resolution: Updated to "email/password and OAuth2 providers"

Real-World Examples

Quarterly Specification Refresh

A SaaS team ran the skill against their product spec after a quarter of development. It identified 34 sections needing updates based on committed code changes, 8 new features not yet in the spec, and 3 specified features that were descoped. The generated change report helped the product manager update stakeholders efficiently.

spec_file: product-spec-v2.md
sections_total: 85
sections_updated: 34
sections_added: 8
sections_removed: 3
conflicts_resolved: 5

highlights:
  - "Payment processing switched from Stripe to Adyen"
  - "Mobile app scope reduced to iOS only for v1"
  - "Real-time notifications added (not in original spec)"
  - "Admin dashboard moved to Phase 2"

Advanced Tips

Link specification sections to implementation files so updates can be triggered when code changes. Use the conflict detection feature to surface decisions that need stakeholder input. Schedule regular specification reviews rather than waiting for large divergences to accumulate.

When to Use It?

Use Cases

  • Sprint Reviews update specs to reflect completed and modified features
  • Requirement Changes incorporate stakeholder feedback into existing specs
  • Technical Discoveries document constraints found during implementation
  • Compliance Updates keep specifications accurate for audit requirements
  • Release Documentation ensure specs match the actual shipped product

Related Topics

When updating specifications, these prompts activate the skill:

  • "Update the specification with these changes"
  • "Revise the spec to match current implementation"
  • "Incorporate this feedback into the requirements document"
  • "Refresh the specification based on sprint results"

Important Notes

Requirements

  • An existing specification document in markdown or structured format
  • Clear description of changes to incorporate
  • Access to related specification sections for cascade updates
  • Works with any document structure and formatting conventions

Usage Recommendations

Do:

  • Update specs at regular intervals rather than waiting for major drift
  • Review conflict resolutions carefully before accepting automated changes
  • Maintain a change log for audit and traceability purposes
  • Share update summaries with all stakeholders after revisions

Don't:

  • Let specs diverge for months as catching up becomes overwhelming
  • Accept all updates without review since some may need human judgment
  • Remove historical context from specs as it explains design decisions
  • Update specs without notifying the team since alignment requires communication

Limitations

  • Cannot determine which code changes represent intentional deviations versus bugs
  • Conflict resolution may require domain expertise beyond automated analysis
  • Very large specifications may need section by section updating rather than full passes
  • Cannot access implementation code directly without being pointed to relevant files