Skill 2: SDD-Fix-Architecture
What SDD-Fix-Architecture Does
This step is optional but recommended.
Takes the architectural problems vFunction found and resolves each one in the specifications, not in the code. Every fix is written as a proposed delta under changes/pending/. No baseline spec file and no source file is ever modified. After a run, the specs still describe the architecture as it is, with the fixes alongside as proposals.
One sub-agent works each finding, in parallel by default. Four kinds of finding are covered:
| Smell | What it is |
|---|---|
| Circular flows | A runtime call stack that leaves a domain, passes through others, and re-enters the first |
| Domain dependency cycles | A cycle in the domain dependency graph; the platform picks which edge to remove |
| Cross-domain dependencies | One unwanted dependency from a named domain into another |
| Shared resources | A resource reached from several domains, with one chosen to own it exclusively |
Example prompts
Fix the architecture TODOs in ../specs/ (the codebase is at ./src)
Fix the circular flows in ../specs/, codebase at ./src
Remove the cross-domain dependencies in my specs at ../specs/ (source: ./src)
Fix the shared tables exclusivity issues in ../specs/
The codebase path is required. A fix cannot be judged without seeing the implementation that the specs deliberately omit.
What You Get
../specs/changes/pending/fix-NN-<scope>/ # change-level documents at the root
../specs/<domain>/changes/pending/fix-NN-<scope>/ # the per-domain delta
Each fix reports one of four outcomes, and they mean different things:
- Resolved. A delta covering the whole finding.
- Partly resolved. A delta covering part of the finding and declaring the rest. This is normal, not a failure: a finding decomposes into parts, and a blocker in one part blocks only that part.
- Not resolvable. Every approach was worked and found blocked, and nothing was written. This needs a human decision.
- No prompt obtainable. The finding’s details could not be fetched, so nothing was attempted. This indicates a stale TODO or a lookup failure, not a verdict that the architecture cannot be fixed. Re-run the vFunction analysis and try again.
Before Moving On
Run this step before sdd-sanitize-specs, not after.
The fixers map each finding onto requirements through traceability.md and the *.evidence.md files, which are exactly the files sanitization deletes. Fixing a sanitized tree leaves the fixers working from the codebase alone, which is slower and weaker.
The same specs-directory guidance given in the Prerequisites applies here, including the Kiro recommendation to use a sub-directory such as ./specs/.
Next SDD Pipeline Skill
The next SDD Pipeline Skill is: