| name | sdlc-solution-spec-workflow |
| description | Use only when the user explicitly invokes this skill to coordinate a multi-artifact solution package across HLD, LLD, domain, ADR, NFR, and SPEC slices. |
| metadata | {"version":"1.0","updated":"2026-07-26"} |
Solution Spec Workflow
Use this workflow when SDLC manager materials need a solution-level package before dev execution.
A solution package connects SRS/NFR/HLD/LLD/ADR/Domain Boundary Map/SPEC materials to an implementation approach. This workflow coordinates and summarizes those artifacts; it should not replace the dedicated sdlc-hld-workflow, sdlc-lld-workflow, sdlc-domain-boundary-modeling, sdlc-modular-monolith-architecture, or sdlc-architecture-decision-record workflows when those artifacts need to be authored in full.
Dev consumes the solution package, maps it to the repository, implements, and reports contradictions or blockers.
Use when
- A feature affects architecture, modules, integration, data flow, API contracts, permission boundaries, migration, observability, release strategy, or multiple code areas.
- SRS, NFR, HLD, LLD, ADR, Domain Boundary Map, or SPEC slices exist, but dev still needs a coherent implementation context.
- The user asks to assemble or normalize a solution design package, technical design package, design doc, implementation approach, or system design material.
- There are alternatives, trade-offs, dependencies, or platform constraints that must be captured before implementation.
- A prior technical bridge must be upgraded into a delivery-grade solution spec.
Do not use when
- The task only needs BRD, URS, PRD, or SRS.
- The implementation is already local, scoped, and clear enough for dev.
- The user wants code edits, tests, debugging, or PR review.
- The user asks only to author a standalone HLD. Use
sdlc-hld-workflow.
- The user asks only to author a standalone LLD. Use
sdlc-lld-workflow.
- The user asks only to model domains, bounded contexts, or data ownership. Use
sdlc-domain-boundary-modeling.
- The user asks only to record an architecture decision. Use
sdlc-architecture-decision-record.
- Required behavior is not specified yet. Use
sdlc-srs-workflow or sdlc-spec-slice-writer first.
- The task is only to generate dev task cards. Use
sdlc-dev-handoff-planning.
Inputs
Prefer:
- SRS
- NFR spec
- HLD
- LLD
- ADR
- Domain Boundary Map
- SPEC slices
- scope baseline
- non-goals
- repository map or project research
- current architecture notes
- API/data docs
- previous design decisions
- incident or bug history
- dependency and platform constraints
- rollout or migration requirements
- open questions from SDLC coordination artifacts
If repo evidence is unavailable, mark solution material as proposed. Do not claim it reflects current code reality.
Solution package levels
Choose the required level.
| Level | Use for |
|---|
| HLD coordination | summarize or link system boundaries, components, flows, integrations, data movement, major dependencies from sdlc-hld-workflow |
| LLD coordination | summarize or link module responsibilities, interfaces, algorithms, state transitions, error handling, migration steps from sdlc-lld-workflow |
| Domain coordination | summarize or link domain ownership, data ownership, allowed dependencies, and forbidden dependencies from sdlc-domain-boundary-modeling |
| ADR coordination | summarize or link architecture decisions, alternatives, consequences, and review conditions from sdlc-architecture-decision-record |
| Constraint spec | technical constraints, non-goals, forbidden approaches, compatibility requirements |
| Implementation guide | ordered implementation approach for dev handoff without editing code |
A solution package may include multiple levels, but do not include sections with no decision or implementation value.
Workflow
1. Establish design scope
Write:
Feature/system:
Source SRS:
Source NFR:
Source HLD:
Source LLD:
Source ADR:
Source Domain Boundary Map:
Source SPEC slices:
Delivery profile:
Repository evidence available:
Design level needed:
Implementation areas:
Out-of-scope technical areas:
Make clear whether the spec is:
evidence-grounded
proposed
decision-needed
2. Identify source requirements
Create a requirement intake table:
| Source ID | Requirement summary | Quality constraint | SPEC slice | Solution impact |
|---|
Every major solution element should trace back to a requirement, NFR, or explicit constraint.
If HLD, LLD, ADR, or Domain Boundary Map is missing but needed, mark it as a required upstream artifact rather than writing a full replacement inside this workflow.
3. Define goals and non-goals
Use goals and non-goals for the solution, not product scope.
Examples:
| Type | Examples |
|---|
| Solution goal | preserve API compatibility, isolate new module, avoid data loss, support rollback |
| Solution non-goal | redesign unrelated service, migrate all old state, replace auth system |
Do not use solution goals to expand product scope.
4. Map system context
For HLD-oriented material, describe:
- user/client actors
- external systems
- internal systems or modules
- data stores
- third-party dependencies
- trust boundaries
- critical flows
- deployment or runtime boundaries if relevant
If this information is substantial or contested, recommend
sdlc-hld-workflow; do not invoke it from this workflow.
Recommended table:
| Component / system | Role | Owned by | Inputs | Outputs | Constraints |
|---|
5. Describe architecture approach
Include only what is needed for dev execution.
## Architecture Approach
- Current state:
- Proposed state:
- Components affected:
- Integration points:
- Data flow:
- Permission model impact:
- Error handling approach:
- Rollout / rollback approach:
- Operational impact:
When there are alternatives, write a decision matrix:
| Option | Description | Pros | Cons | Risks | Decision |
|---|
If the decision is long-lived or affects HLD, LLD, SPEC, RTM, or future
implementation, recommend sdlc-architecture-decision-record; do not invoke it
automatically. Link an existing or user-approved ADR here.
6. Define API and interface approach
If relevant, summarize interface behavior and link to API SPEC.
Include:
- public API surface
- internal interface surface
- versioning
- backward compatibility
- error model
- idempotency
- rate limit or abuse controls
- event/webhook behavior
- client migration impact
Do not duplicate the full API SPEC unless this document is the only artifact being produced.
7. Define data and state approach
If relevant, summarize:
- entities or records affected
- state transitions
- schema or field impact
- migration path
- backfill or reconciliation
- retention and deletion
- privacy classification
- data consistency model
- audit trail
Use sdlc-spec-slice-writer for detailed Data SPEC when needed.
8. Define module and directory approach
If repository evidence is available, map proposed work to existing conventions:
| Area | Existing convention | Proposed change | Reason | Risk |
|---|
If evidence is missing, write:
Repository evidence needed before finalizing directory or module placement.
Do not invent paths as facts. You may propose candidate areas if clearly marked.
For modular-monolith directory and dependency rules, recommend
sdlc-modular-monolith-architecture or Directory SPEC, then summarize only
constraints already accepted by the user.
9. Define LLD-oriented implementation notes
For each module or capability, use:
### <Module / capability>
- Source requirement IDs:
- Responsibility:
- Inputs:
- Outputs:
- Main logic:
- State changes:
- Error handling:
- Data access:
- External calls:
- Observability:
- Tests needed:
- Open questions:
This is not code. It is a dev-readable implementation contract.
If the notes become detailed module design, recommend sdlc-lld-workflow; do
not invoke it from this workflow.
10. Define validation strategy
Map requirements to validation types:
| Requirement / NFR | Validation type | Suggested check | Blocks release? |
|---|
Validation types:
unit
integration
contract
UI / E2E
migration
security
privacy
performance
accessibility
manual smoke
observability
release rollback
11. Define rollout and rollback
If release risk exists, include:
- feature flag needs
- migration sequencing
- beta or staged rollout
- monitoring before expansion
- rollback conditions
- rollback steps
- data recovery considerations
- support notes
12. Record risks and decisions
Use two separate tables.
Decision log:
| ID | Decision | Basis | Alternatives rejected | Owner | Date / version |
|---|
Risk log:
| ID | Risk | Source | Impact | Mitigation | Owner | Blocks dev? |
|---|
Do not bury risks inside prose.
13. Prepare dev-facing handoff notes
Summarize what dev should use:
- implementation areas
- source artifacts
- non-goals
- constraints
- validation requirements
- open blockers
- contradictions to resolve
- suggested order of work
Recommend sdlc-dev-handoff-planning when task cards are needed; do not invoke
it automatically.
Output
Return or write:
# Solution Spec: <Feature / System>
## 1. Document Control
## 2. Source Requirements and Constraints
## 3. Goals and Non-goals
## 4. System Context
## 5. Architecture Approach
## 6. Interface / API Approach
## 7. Data and State Approach
## 8. Module / Directory Approach
## 9. LLD-oriented Implementation Notes
## 10. Validation Strategy
## 11. Rollout and Rollback
## 12. Architecture / Domain Artifact Links
## 13. Decision Log
## 14. Risk Log
## 15. Open Questions
## 16. Dev Handoff Notes
Validation
Before calling the solution spec ready:
- Every major solution element links to SRS, NFR, SPEC, or an explicit constraint.
- Goals and non-goals are technical/solution-scoped, not product scope drift.
- Assumptions are marked as assumptions.
- Repo-dependent claims are evidence-grounded or marked as proposed.
- Alternatives are recorded for major decisions.
- HLD, LLD, ADR, Domain Boundary Map, and Directory SPEC are linked when present or marked missing when needed.
- Data, permission, security, privacy, observability, and release impact were considered when relevant.
- Validation strategy covers changed behavior and blocking NFRs.
- Rollout and rollback are included when release risk exists.
- Open questions are separated from decisions.
- Dev handoff notes are concrete enough for
sdlc-dev-handoff-planning.
Boundaries
- Do not edit code.
- Do not run tests as part of this skill.
- Do not approve or reject product scope.
- Do not override SRS, NFR, or SPEC artifacts without an explicit change-control path.
- Do not claim final repository fit without evidence.
- Do not use this workflow to hide missing HLD, LLD, ADR, or domain-boundary work that should be authored explicitly.
- Do not require dev sign-off for the SRS; dev should consume artifacts and report blockers or contradictions.
- Do not turn this skill into a project management plan. Use it to make implementation context precise.
Handoff
Recommend at most one downstream skill after completing the requested package.
Do not invoke it automatically:
For an explicit-control workflow, return its exact
$codex-next:<skill-name> command and stop.
| Need | Next skill |
|---|
| missing software requirements | sdlc-srs-workflow |
| missing measurable quality requirements | sdlc-nfr-spec |
| missing HLD | sdlc-hld-workflow |
| missing LLD | sdlc-lld-workflow |
| missing domain boundary or ownership map | sdlc-domain-boundary-modeling |
| missing modular monolith structure | sdlc-modular-monolith-architecture |
| missing architecture decision record | sdlc-architecture-decision-record |
| missing UI/API/Data/Admin/Permission slices | sdlc-spec-slice-writer |
| executable implementation task package | sdlc-dev-handoff-planning |
| requirement-to-task/test traceability | sdlc-requirements-traceability |
| readiness judgment | $codex-next:sdlc-readiness-review |
When handing off to dev, provide:
- source artifact list
- solution goals and non-goals
- component or module map
- architecture and domain constraints
- allowed and forbidden dependencies
- validation requirements
- risk log
- open blockers
- suggested implementation order
