- Introduction
- Overview: The SpecOps Process
- Phase 1: Discovery and Assessment
- Phase 2: Specification Generation
- Phase 3: Specification Verification
- Phase 4: Modern Implementation
- Phase 5: Testing and Validation
- Phase 6: Deployment and Knowledge Transfer
- Integration with Strangler Fig Pattern
- Conclusion
This document provides practical guidance for implementing the SpecOps approach to legacy system modernization. It walks through the complete process from initial assessment to production deployment, with specific steps, roles, deliverables, and decision points clearly defined.
The methodology is designed to be:
- Iterative: Work on portions of the system incrementally rather than attempting everything at once
- Verifiable: Build in checkpoints where domain experts confirm correctness
- Flexible: Adapt the process to your organization's constraints and capabilities
- Practical: Focus on achievable outcomes with realistic resource requirements
The SpecOps methodology consists of six primary phases:
- Discovery and Assessment - Understand the legacy system and plan the modernization approach
- Specification Generation - Use AI agents to create initial specifications from legacy code
- Specification Verification - Domain experts review and validate specifications
- Modern Implementation - Generate new code from verified specifications
- Testing and Validation - Verify the implementation matches the specification
- Deployment and Knowledge Transfer - Move to production and preserve institutional knowledge
Each phase has specific inputs, activities, outputs, and quality gates that must be satisfied before proceeding.
Understand the scope of the legacy system, identify stakeholders, assess available resources, and create a prioritized plan for specification development.
What: Document what you're working with
- Identify all components of the legacy system (applications, databases, batch jobs, integrations)
- Map data flows between components
- Document programming languages, frameworks, and technologies used
- Identify existing documentation (however sparse)
- Locate source code repositories
Deliverable: System component inventory with technology stack details
What: Find the people who know and care about this system
- Identify domain experts (policy, program, business rules)
- Find technical experts (even if retired, can they consult?)
- Locate current system users and administrators
- Identify decision-makers and approval authorities
- Map regulatory and compliance stakeholders
Deliverable: Stakeholder roster with roles, expertise areas, and availability
What: Understand what's known and unknown about the system
- Interview stakeholders about system behavior
- Review existing documentation (requirements, design docs, user guides)
- Identify areas where knowledge has been lost
- Document critical business rules and edge cases people remember
- Assess test coverage and test data availability
Deliverable: Knowledge assessment report highlighting gaps and risks
What: Decide what to specify first
- Rank components by business criticality
- Assess complexity and risk for each component
- Consider knowledge loss urgency (what's at risk of being lost first?)
- Identify dependencies between components
- Evaluate potential seams for Strangler Fig modernization
- Consider which components could be built new vs. replaced
- Balance quick wins with critical needs
Prioritization Criteria:
- Business criticality (High/Medium/Low)
- Knowledge loss risk (High/Medium/Low)
- Complexity (High/Medium/Low)
- Dependencies on other components (Many/Some/Few)
- Stakeholder availability for verification (Good/Limited/Poor)
- Suitability for incremental replacement (Good seam/Moderate/Poor)
Strangler Fig Considerations: When prioritizing for Strangler Fig modernization, also consider:
- Edge components first: Components at system boundaries are easier to replace
- New features: Can new functionality be built in modern code from the start?
- Clear interfaces: Components with well-defined integration points are good candidates
- Business value: Which replacements would deliver most value soonest?
Deliverable: Prioritized list of components for specification development, with Strangler Fig modernization strategy
What: Establish the SpecOps infrastructure
- Select AI coding agents based on legacy languages and modern targets
- Set up specification repository structure
- Identify or create needed instruction sets for AI agents
- Configure review and approval workflows
- Establish testing infrastructure
Deliverable: Configured SpecOps toolchain ready for use
What: Choose a component to prove the approach
- Select a moderate-complexity component with known behavior
- Ensure domain expert availability for verification
- Choose something small enough to complete in 2-4 weeks
- Pick something valuable enough to demonstrate ROI
Deliverable: Pilot component selection with success criteria
- System components documented and prioritized
- Key stakeholders identified and engaged
- SpecOps toolchain configured
- Pilot component selected
- Resources allocated and timeline established
Use AI agents with appropriate instruction sets to analyze legacy code and generate initial specifications describing system behavior.
What: Create or select the skills needed for this component
- Review available instruction sets (COBOL comprehension, domain-specific, etc.)
- Customize instructions for this specific system's patterns
- Define specification structure and format
- Establish terminology and glossary
- Create examples of desired specification output
Deliverable: Configured AI agent instruction sets for this component
What: Have AI agents analyze the legacy code
- Feed legacy source code to AI agents with comprehension instructions
- Extract business logic from technical implementation
- Identify data structures and their relationships
- Document control flows and decision points
- Flag areas of uncertainty or ambiguity
Process:
- Start with entry points (main programs, transaction handlers)
- Follow call graphs through the component
- Document each logical unit (subroutine, paragraph, module)
- Identify cross-cutting concerns (error handling, logging, security)
- Note dependencies on other components or external systems
Deliverable: AI-generated analysis notes and preliminary specifications
What: Convert analysis into structured specifications
- Organize information into specification structure
- Write clear, plain-language descriptions of behavior
- Include concrete examples for complex logic
- Document edge cases and error handling
- Cross-reference related specifications
Specification Contents:
- Purpose: What this component does and why it exists
- Inputs: What data or events trigger this behavior
- Business Rules: The logic and decisions being made
- Outputs: What results or effects are produced
- Data Structures: Schemas, formats, and relationships
- Dependencies: What this component relies on
- Edge Cases: Unusual conditions and how they're handled
- Uncertainties: Areas where AI or human reviewers are unsure
Deliverable: Draft specifications in the specification repository
What: Engineers review specifications for technical accuracy
- Verify AI correctly understood code structure
- Check that data flows are accurately represented
- Confirm technical dependencies are identified
- Flag any obvious misunderstandings or gaps
- Assess completeness of coverage
Deliverable: Technically-reviewed draft specifications with issues logged
What: Address technical review feedback
- Correct misunderstandings identified in review
- Fill gaps in specification coverage
- Clarify ambiguous descriptions
- Add detail where needed for clarity
- Update cross-references and dependencies
Deliverable: Refined specifications ready for domain expert verification
- Draft specifications created for all prioritized components
- Specifications technically reviewed by engineers
- Technical issues resolved
- Specifications organized and formatted consistently
- Uncertainties and questions documented for domain expert review
Domain experts review specifications to confirm they accurately describe system behavior, business rules, and policy implementation.
What: Organize the review process
- Assign specification sections to appropriate domain experts
- Schedule review sessions and workshops
- Prepare supporting materials (examples, test cases, policy references)
- Set up collaboration tools (PR reviews, comment threads)
- Establish review timeline and milestones
Deliverable: Verification plan with assignments and schedule
What: Experts verify specifications match their understanding
- Domain experts read assigned specification sections
- Compare specifications to their knowledge of system behavior
- Verify business rules are correctly captured
- Check that edge cases are properly handled
- Confirm policy implementation is accurate
- Flag discrepancies, errors, or omissions
Review Methods:
- Individual review: Experts read and comment asynchronously
- Walkthrough sessions: Present specifications and discuss together
- Example validation: Test specifications against known scenarios
- Policy comparison: Verify against authoritative policy sources
- User perspective: Validate from end-user experience
Common Issues to Watch For:
- Business rules stated incorrectly
- Edge cases missing or wrong
- Policy misinterpretations
- Terminology misuse
- Incomplete coverage of scenarios
- Contradictions between specification sections
Deliverable: Domain expert comments, questions, and approval status
What: Resolve discrepancies and uncertainties
- Investigate each issue raised by domain experts
- Re-examine legacy code to clarify ambiguities
- Consult additional sources (documentation, test data, users)
- Update specifications based on verified corrections
- Document rationale for specification decisions
When Experts Disagree:
- Research policy and legislative sources
- Examine actual system behavior through testing
- Consult with users about real-world usage
- Escalate to decision-makers if needed
- Document the disagreement and resolution
Deliverable: Updated specifications with issues resolved
What: Obtain formal sign-off on verified specifications
- Domain experts formally approve their sections
- Record who approved what and when
- Note any caveats or conditions on approval
- Mark specifications as "verified" in repository
- Create audit trail of verification process
Approval Levels:
- Fully Verified: Expert confirms complete accuracy
- Verified with Caveats: Accurate but with noted limitations
- Best Effort: No expert available, best understanding documented
- Requires Research: Needs additional investigation before implementation
Deliverable: Approved specifications with verification status metadata
What: Document insights gained during verification
- Record clarifications provided by domain experts
- Document rationale for business rules
- Capture tribal knowledge revealed during review
- Note policy interpretations and their sources
- Update glossary with confirmed terminology
Deliverable: Enhanced specifications with contextual knowledge
- All specifications reviewed by appropriate domain experts
- Discrepancies investigated and resolved
- Specifications formally approved
- Verification status documented
- Institutional knowledge captured in specifications
Generate modern code from verified specifications using AI agents, following contemporary design patterns and best practices.
What: Define the technical approach for the new implementation
- Select target technology stack
- Define architecture and design patterns
- Identify reusable components or services
- Plan data migration approach
- Establish coding standards and conventions
Deliverable: Technical implementation plan
What: Configure AI agents for code generation
- Create or select instruction sets for target technologies
- Define code structure and organization
- Establish patterns for common scenarios
- Configure testing approach
- Set quality and security standards
Deliverable: Implementation instruction sets for AI agents
What: Use AI agents to generate modern code from specifications
- Feed verified specifications to AI agents with implementation instructions
- Generate code component by component
- Apply modern design patterns and practices
- Include error handling and logging
- Generate initial test cases
Process:
- Start with data models and schemas
- Generate core business logic
- Add integration layers
- Implement user interfaces (if applicable)
- Create supporting infrastructure code
Code Generation Principles:
- Generate clean, maintainable code
- Follow modern conventions for target stack
- Include comprehensive error handling
- Implement proper logging and observability
- Generate with testability in mind
Deliverable: Generated modern code in version control
What: Engineers review and improve generated code
- Review code for quality and correctness
- Verify it implements the specification accurately
- Refactor for clarity and maintainability
- Add comments and documentation
- Address security and performance concerns
Review Checklist:
- Code correctly implements specification
- Follows coding standards and conventions
- Includes appropriate error handling
- Has adequate logging and observability
- Meets security requirements
- Performs acceptably
- Is maintainable and well-documented
Deliverable: Reviewed and refined implementation code
What: Create comprehensive tests based on specifications
- Generate test cases from specification examples
- Create unit tests for business logic
- Develop integration tests for component interactions
- Build end-to-end tests for user scenarios
- Prepare test data based on real-world examples
Test Coverage:
- All business rules specified
- Edge cases documented in specifications
- Error conditions and handling
- Data validation and transformation
- Integration points and dependencies
Deliverable: Comprehensive test suite
- Modern code generated from verified specifications
- Code reviewed and refined by engineers
- Coding standards and quality requirements met
- Comprehensive tests created
- Code documented and ready for testing
Verify that the modern implementation correctly realizes the verified specification and produces results equivalent to the legacy system.
What: Run automated tests against the implementation
- Execute unit tests for individual components
- Run integration tests for component interactions
- Verify business logic correctness
- Test error handling and edge cases
- Confirm data validation works correctly
Deliverable: Test results with all tests passing
What: Verify implementation matches the specification
- Test each behavior described in the specification
- Validate examples from specifications work correctly
- Confirm edge cases are handled as specified
- Check that constraints and validations match specs
- Verify error messages and handling are correct
Approach:
- Use specifications as test oracles
- Create traceability matrix linking tests to spec sections
- Ensure every specification requirement has corresponding tests
Deliverable: Conformance test results showing specification compliance
What: Compare modern and legacy system outputs
- Identify comparable test scenarios
- Run same inputs through both systems
- Compare outputs for equivalence
- Investigate and explain any differences
- Determine if differences are acceptable or errors
Comparison Strategies:
- Parallel testing: Run both systems simultaneously
- Shadow mode: Process production data through both
- Regression testing: Use historical test data and expected results
- Sampling: Test representative subset of scenarios
Handling Differences:
- Some differences may be intentional improvements
- Document why outputs differ when they do
- Get domain expert approval for acceptable differences
- Fix errors where modern system is wrong
Deliverable: Comparison test results with differences explained and approved
What: Validate with actual users and stakeholders
- Have real users test the modern system
- Verify it meets their needs and expectations
- Gather feedback on usability and functionality
- Identify any gaps or issues not caught in earlier testing
- Confirm it's ready for production use
Deliverable: UAT results and stakeholder approval
What: Ensure the system performs adequately
- Test under realistic load conditions
- Verify response times are acceptable
- Confirm resource usage is reasonable
- Identify and address bottlenecks
- Validate scalability if needed
Deliverable: Performance test results meeting requirements
What: Verify security and regulatory requirements
- Run security scans and penetration tests
- Verify compliance with relevant regulations
- Test access controls and authentication
- Validate data protection measures
- Confirm audit logging is adequate
Deliverable: Security and compliance certification
- All automated tests passing
- Specification conformance verified
- Legacy system comparison complete and differences explained
- User acceptance testing successful
- Performance requirements met
- Security and compliance requirements satisfied
- Stakeholder approval obtained for production deployment
Deploy the modern system to production, preserve institutional knowledge, and ensure ongoing maintenance is sustainable.
What: Prepare for production rollout
- Define deployment strategy (big bang, phased, parallel run)
- Design transitional architecture for Strangler Fig coexistence
- Create rollback plan
- Prepare production environment
- Schedule deployment window
- Communicate with stakeholders
Deployment Strategies:
- Big Bang: Switch completely at once (risky, fast)
- Phased: Roll out to user groups incrementally (lower risk)
- Parallel Run: Run both systems simultaneously (safest, most expensive)
- Canary: Deploy to small subset first (good for validation)
- Strangler Fig: New component coexists with legacy, gradually taking over (best for incremental modernization)
Transitional Architecture Considerations: For Strangler Fig deployments, design infrastructure that enables:
- Routing logic: Direct traffic to legacy or modern based on capability
- Data synchronization: Keep legacy and modern data stores consistent if needed
- Monitoring: Track which system handles which requests
- Fallback: Ability to route back to legacy if modern component has issues
- Gradual migration: Increase modern component traffic as confidence grows
Deliverable: Deployment plan with timeline, transitional architecture design, and rollback procedures
What: Move data from legacy to modern system (if applicable)
- Extract data from legacy system
- Transform to modern data structures
- Validate data integrity and completeness
- Load into modern system
- Verify migration success
Deliverable: Migrated and validated data in modern system
What: Execute the deployment
- Deploy modern system to production
- Switch traffic from legacy to modern system
- Monitor closely for issues
- Be ready to roll back if needed
- Validate production behavior
Deliverable: Modern system running in production
What: Ensure the organization can maintain the new system
- Train development and operations staff
- Document operational procedures
- Transfer domain knowledge from retiring experts
- Create runbooks and troubleshooting guides
- Establish support processes
Knowledge Transfer Contents:
- How the system works (architecture, design)
- Where specifications are and how to update them
- How to make changes using SpecOps process
- Common issues and their resolutions
- Who to contact for different types of questions
Deliverable: Trained staff and comprehensive operational documentation
What: Update specifications to reflect production reality
- Document any changes made during testing and deployment
- Capture lessons learned
- Update specifications with production-specific details
- Tag release version in specification repository
- Archive for historical reference
Deliverable: Final, production-accurate specifications
What: Retire the legacy system
- Archive legacy code and data per retention requirements
- Document what was replaced and when
- Preserve institutional knowledge captured during modernization
- Transfer any remaining responsibilities
- Celebrate the modernization success!
Deliverable: Legacy system properly archived and decommissioned
- Modern system successfully deployed to production
- Data migrated and validated
- Staff trained and ready to maintain system
- Specifications finalized and archived
- Legacy system decommissioned
- Knowledge preserved for future reference
The SpecOps methodology is designed to be applied incrementally rather than attempting to modernize entire systems at once. This approach aligns naturally with the Strangler Fig pattern of legacy modernization—a gradual process where new components are built alongside the legacy system, slowly replacing it piece by piece until the legacy system can be retired.
The Strangler Fig pattern, named after vines that gradually replace their host trees, advocates for:
- Building new functionality incrementally alongside the legacy system
- Identifying seams in the legacy system where components can be separated
- Gradually moving behavior from legacy to modern implementation
- Maintaining coexistence between old and new until modernization is complete
- Building transitional architecture to enable this gradual replacement
SpecOps enhances the Strangler Fig pattern by adding a critical capability: comprehensive specifications that serve as a bridge between legacy and modern systems.
In traditional Strangler Fig modernization, teams must:
- Understand what a legacy component does
- Build a modern replacement
- Ensure the replacement behaves equivalently
- Route traffic from legacy to modern component
SpecOps adds a crucial artifact between steps 1 and 2: a verified specification that defines the component's behavior. This specification serves as:
- Documentation of what the legacy component does
- Contract for what the modern component must do
- Test oracle for verifying equivalence
- Integration specification defining how components interact
This makes Strangler Fig modernization more reliable because there's an explicit, verified definition of required behavior rather than hoping you've understood the legacy code correctly.
The SpecOps discovery phase naturally helps identify seams in the legacy system:
- Component boundaries become clear during specification generation
- Dependencies are explicitly documented in specifications
- Data flows between components are mapped
- Integration points are identified and specified
This specification-driven analysis makes it easier to find the seams needed for Strangler Fig modernization. Rather than hoping you've identified good boundaries, specifications make dependencies explicit and help evaluate different options for where to cut the system.
During Strangler Fig modernization, legacy and modern systems often need to coexist, sometimes for years. SpecOps supports this by:
Specifications enable parallel validation: Run the same scenarios through both systems and compare against the specification to verify equivalence
Specifications guide routing logic: The transitional architecture that routes some requests to legacy and others to modern can use specifications to determine which components are ready to handle which scenarios
Specifications document coexistence: Clear documentation of which behaviors are handled by legacy vs. modern components, helping manage the transitional period
- Apply SpecOps Discovery to the entire legacy system (or major subsystem)
- Identify seams and potential component boundaries
- Prioritize components for specification and modernization
- Create specifications for cross-cutting concerns and integration points
- Set up transitional architecture infrastructure
Deliverable: Understanding of system structure with identified seams and prioritized modernization roadmap
- Generate specifications for the first component cluster
- Verify specifications with domain experts
- Document the seam between this cluster and the rest of the system
- Define the integration contract in specification form
Deliverable: Verified specifications defining a separable component cluster
- Generate modern implementation from verified specifications
- Test against specification (not just against legacy behavior)
- Create adapter/façade for integration with remaining legacy system
- Deploy modern component alongside legacy
Deliverable: Modern component coexisting with legacy system
- Route a small percentage of traffic to modern component
- Monitor for issues and differences
- Validate against specifications
- Gradually increase traffic to modern component
- Keep legacy component running during validation period
Deliverable: Modern component handling production traffic
- Once modern component is fully validated, retire legacy component
- Archive specifications and code
- Remove transitional architecture for this component
- Document what was replaced and when
Deliverable: Legacy component decommissioned, modern component fully operational
- Apply learning from first iteration
- Repeat process for next prioritized component
- Build on existing specifications and modern code
- Continue until legacy system is fully replaced
When selecting which components to modernize in what order, consider both SpecOps and Strangler Fig principles:
SpecOps Priorities:
- Components with available domain experts
- Lower complexity for learning
- Well-understood behavior
Strangler Fig Priorities:
- Components at the edge of the system (easier seams)
- New features that can be built in modern code from the start
- Components with clear boundaries
Combined Strategy: Select edge components with moderate complexity where domain experts are available. This proves both the SpecOps process and the Strangler Fig approach with manageable risk.
SpecOps Priorities:
- Business-critical logic where specifications are most valuable
- Components where institutional knowledge is at risk
- Complex business rules needing verification
Strangler Fig Priorities:
- Components that would benefit most from modern technology
- Areas where the business needs new capabilities
- Components where coexistence costs are manageable
Combined Strategy: Tackle core business logic where the specification becomes valuable documentation even if modernization takes time. The specification enables confident replacement when ready.
SpecOps Priorities:
- Remaining complex components
- Cross-cutting concerns and infrastructure
- Final integration points
Strangler Fig Priorities:
- Core infrastructure components
- Components with many dependencies (saved for last)
- Final removal of transitional architecture
Combined Strategy: Complete the modernization with accumulated experience and a library of specifications. The final components benefit from established patterns and existing modern infrastructure.
The transitional period—when legacy and modern systems coexist—can last months or years for large systems. SpecOps provides tools to manage this:
Specifications can inform routing decisions:
If scenario matches verified specification for Component X:
Route to modern implementation
Else:
Route to legacy system
This allows gradual expansion of modern component capabilities based on specification coverage.
During coexistence, specifications serve as the test oracle:
- Run same inputs through both systems
- Compare outputs to specification requirements (not just to each other)
- Modern system is correct if it matches specification, even if legacy behaves differently
- Investigate and document any differences
Specifications make the transitional state explicit:
- Which behaviors are in modern vs. legacy
- Which integration points exist
- What transitional architecture is in place
- When each component was modernized
This visibility is crucial for managing the extended transitional period.
Risk Reduction Through Verification Strangler Fig reduces risk by making changes incrementally. SpecOps reduces risk further by verifying component behavior before building replacements.
Earlier Value Delivery Strangler Fig delivers value as each component is replaced. SpecOps can deliver value even earlier—the specifications themselves are valuable for training, audit, and documentation before any code is written.
Better Seam Identification Specifications make component boundaries and dependencies explicit, making it easier to find good seams for the Strangler Fig approach.
Preserved Knowledge During Long Transitions Legacy modernization can take years. During this time, domain experts may retire. SpecOps ensures their knowledge is captured in specifications early, even if modernization of some components happens much later.
Clearer Success Criteria Strangler Fig requires knowing when a replacement is "good enough" to retire the legacy component. Specifications provide clear criteria: if the modern component correctly implements the verified specification, it's ready.
Reduced Transitional Architecture Complexity With clear specifications defining component contracts, the transitional architecture that enables coexistence can be simpler and more reliable.
This combined approach is particularly effective when:
- Legacy system is too large or critical to replace all at once
- Business needs new features during modernization
- System must remain operational throughout modernization
- Domain expertise is available but at risk of being lost
- Team wants to learn and adapt as modernization progresses
- Budget and resources must be allocated incrementally
- Risk of "big bang" replacement is unacceptable
Consider a benefits eligibility system built 30 years ago in COBOL:
Traditional Approach: Try to replace the entire system at once. High risk, long timeline, business can't get new features until replacement is complete.
Strangler Fig Alone: Incrementally build modern replacements. But without specifications, each component risks misunderstanding legacy behavior.
SpecOps + Strangler Fig:
-
Year 1: Generate and verify specifications for income verification component. Build modern replacement. Deploy alongside legacy. Route new application types to modern component while legacy handles existing types.
-
Year 2: Generate and verify specifications for benefit calculation rules. Build modern implementation. Domain expert who wrote original logic reviews specifications before retiring. Modern component uses income data from either legacy or modern income verification.
-
Year 3: Generate specifications for appeals processing. Modernize. Modern appeals component works with both legacy and modern eligibility decisions.
-
Year 4: Complete remaining components. Retire legacy system. Comprehensive specifications remain as institutional knowledge.
Throughout this process:
- Specifications provide verified understanding of each component
- Modern and legacy systems coexist safely
- Business gets new features in modernized components
- Institutional knowledge is preserved
- Risk is managed through incremental replacement
- Each year delivers value, not just the final year
This is the power of combining SpecOps with the Strangler Fig pattern: gradual, verified, value-delivering modernization that preserves institutional knowledge.
- Owns overall modernization strategy and timeline
- Coordinates across stakeholders
- Manages risks and issues
- Reports progress to leadership
- Ensures resources are available
- Designs modern architecture
- Configures AI agent instructions
- Reviews generated specifications and code
- Ensures technical quality
- Manages technical infrastructure
- Reviews and verifies specifications
- Provides institutional knowledge
- Clarifies business rules and policy
- Approves specifications
- Validates testing results
- Operates AI agents for specification and code generation
- Reviews and refines generated code
- Develops tests
- Troubleshoots issues
- Maintains modern system
- Designs test strategy
- Executes testing activities
- Compares legacy and modern system behavior
- Documents test results
- Validates quality gates
- Maintains SpecOps toolchain
- Manages specification repository
- Configures CI/CD pipelines
- Deploys to production
- Monitors system health
Decision Criteria:
- Are specifications going to be more valuable than direct translation?
- Do we have domain experts available for verification?
- Can we commit to the iterative approach?
- Do we have necessary tools and skills?
Options:
- Proceed with SpecOps for prioritized components
- Use different approach for some components (hybrid strategy)
- Defer modernization until conditions improve
Quality Criteria:
- Specifications are clear and understandable
- Technical accuracy verified by engineers
- Coverage is comprehensive
- Structure is consistent
- Ready for domain expert review
Options:
- Proceed to verification
- Refine specifications further
- Adjust AI agent instructions and regenerate
Quality Criteria:
- Domain experts have verified specifications
- Discrepancies resolved
- Uncertainties addressed or documented
- Approval obtained
- Institutional knowledge captured
Options:
- Proceed to implementation
- Do additional verification on uncertain areas
- Document areas where verification wasn't possible
Quality Criteria:
- Code correctly implements specifications
- Technical quality standards met
- Comprehensive tests created
- Documentation adequate
- Engineers confident in implementation
Options:
- Proceed to testing
- Refine implementation
- Improve test coverage
Quality Criteria:
- All tests passing
- Specification conformance verified
- Legacy comparison acceptable
- UAT successful
- Performance adequate
- Security approved
- Stakeholders ready
Options:
- Deploy to production
- Address identified issues
- Do additional testing or validation
- Combine phases where appropriate
- Use simpler tooling
- Reduce formality of reviews
- Faster iteration cycles
- More rigorous phase gates
- Extensive stakeholder coordination
- Formal change control
- Parallel teams on different components
- Additional verification steps
- More extensive testing
- Phased deployment approach
- Longer parallel run period
- Focus on highest-value components
- Accept longer timelines
- Use simpler tools
- Leverage external domain experts part-time
- Percentage of legacy system documented in specifications
- Number of domain expert insights captured
- Reduction in "only one person knows this" scenarios
- Percentage of specifications verified by domain experts
- Number of discrepancies found and resolved
- Stakeholder satisfaction with specification accuracy
- Percentage of specification requirements with passing tests
- Number of production defects in modernized components
- Performance compared to legacy system
- Time from specification to production deployment
- Effort required for specification generation vs. manual documentation
- Cost compared to traditional modernization approaches
- Ease of making changes to modernized components
- Onboarding time for new developers
- Reduction in maintenance burden
Problem: Specifications generated but not verified, leading to errors in implementation Solution: Make verification non-negotiable. Better to delay than proceed with unverified specs
Problem: Creating specifications as an afterthought rather than the authoritative source Solution: Establish specification-first culture. All changes start with spec updates
Problem: Accepting AI-generated content without critical review Solution: AI assists but humans verify. Build in checkpoints for human judgment
Problem: Trying to create perfect specifications before proceeding Solution: Iterate. Get specifications "good enough" and refine based on implementation learnings
Problem: Not comparing modern and legacy system behavior Solution: Use legacy system as test oracle. Explain all differences
Problem: Trying to execute SpecOps with inadequate tools Solution: Invest in proper toolchain before starting. Minimum viable is okay but needs basics
Problem: Pushing to production before sufficient validation Solution: Respect phase exit criteria. Stakeholder pressure is real but errors are costly
The SpecOps methodology provides a structured, repeatable approach to legacy system modernization that prioritizes knowledge preservation, domain expert verification, and sustainable outcomes.
By following these phases, maintaining quality gates, and adapting to your specific context, you can successfully modernize legacy systems while capturing institutional knowledge that would otherwise be lost.
The methodology is not prescriptive in every detail—adapt it to your organization's needs, constraints, and culture. The core principles remain: specifications are the valuable artifact, domain experts verify correctness, and AI assists rather than replaces human judgment.
Start small with a pilot, learn from experience, and scale up as you build confidence and capability. SpecOps is as much about building organizational muscle for specification-driven development as it is about modernizing any particular system.