Step 2 - Design & Technical Spec

Once the requirement is clear, we move to design. In the Velocity Framework, non-trivial changes should have a short, written technical spec before coding starts.

The Spec Artifact

For significant changes, create a markdown spec (for example, in a specs/ directory) linked from the ticket.

The spec does not need to be long. It needs to be clear and concrete.

What Goes In the Spec

You can draft the spec with AI assistance, but you own the decisions. At minimum, cover:

1. Goal
   What problem are we solving? How will we know it worked?
2. Proposed changes
   Which modules, services, or components will change? Which new ones will be created?
3. Data and control flow
   How data moves through the system (from DB or upstream APIs to UI or consumers).
4. Schema and contract changes
   Any migrations, new endpoints, or modified interfaces.
5. Security and compliance considerations
   Auth, authz, validation, logging, and any relevant client constraints.
6. Testing strategy
   What kinds of tests we will add or update (unit, integration, E2E), and at which boundaries.

Using AI to Stress-Test the Spec

Use your AI-native IDE or chat tool to challenge the spec:

• "Review this spec. Where are the risks? Any obvious performance or security issues?"
• "List edge cases this spec doesn’t address."
• "Suggest simpler alternatives that achieve the same goal."

You are not asking the AI to approve the spec. You are using it as a reviewer that helps surface issues faster.

Approval and Collaboration

For larger changes:

• Treat the spec like code: open a PR or equivalent review flow.
• Ask a tech lead or AI delivery architect to review and comment.
• Iterate until the spec feels small enough and safe enough to implement.

Adjust the level of formality to the project, but keep the principle: design before code, in writing.