Tips & Best Practices

These are patterns that consistently lead to better outcomes when using SpecSafe.

Start with planning

Do not skip Phase 1 even for features that seem simple. Running brainstorm through readiness takes minutes and catches issues that would cost hours during implementation. The readiness gate exists for a reason: it finds gaps in requirements, missing edge cases, and conflicting assumptions before you write a single line of code.

One spec at a time

Complete or park a spec before starting another. Context switching between specs degrades quality for both. If you need to pause a spec, that is fine, but do not juggle three active specs simultaneously. The status dashboard helps you see what is in flight.

Trust the TDD cycle

Let failing tests drive your code. The /specsafe-test skill generates all tests in a skipped state deliberately. The /specsafe-code skill unskips one test at a time, writes the minimal code to pass it, and refactors before moving on. Do not write implementation code first and then retrofit tests. The cycle is red, green, refactor. Trust it.

Use personas deliberately

Each SpecSafe persona brings unique expertise. Elena explores possibilities and asks divergent questions. Kai structures and organizes information into clear frameworks. Lyra validates and stress-tests assumptions. When you invoke a skill, you get the right persona for that task. For complex decisions, use /specsafe-party-mode to bring multiple personas into the conversation.

Evidence over assertions

QA requires concrete test output, not subjective claims. "It works" is not evidence. "All 47 tests pass, coverage is 94%, and edge cases A, B, and C are handled" is evidence. The QA skill enforces this by requiring test results before issuing a GO recommendation.

UX before architecture

Always design for users before optimizing for systems. If you design the architecture first, you risk hardening assumptions that do not serve the user experience. The SpecSafe skill ordering (PRD, then UX, then architecture) exists to prevent this. Follow the order.

The readiness gate matters

If /specsafe-readiness says NEEDS REVISION, revise. Pushing forward with known gaps costs more time later than fixing them now. The gate checks for completeness, consistency between artifacts, and testability of requirements. A NEEDS REVISION result means specific things are missing or contradictory. Fix them.

Use party mode for complex decisions

Multi-persona sessions bring diverse perspectives to hard problems. Architecture trade-offs, build-vs-buy decisions, and prioritization conflicts all benefit from having multiple viewpoints debate the options. Party mode is not just a novelty; it surfaces blind spots that a single perspective misses.

Archive, do not delete

Use /specsafe-archive for specs that are abandoned or obsolete. Deleted specs leave no trace. Archived specs preserve the reasoning, decisions, and context for future reference. When someone asks "why did we not do X?", the archived spec has the answer.

Keep specs atomic

One feature per spec. Large specs that cover multiple features are hard to test, hard to validate, and hard to complete. If a feature feels too big for one spec, break it into smaller, independently deliverable pieces. Each spec should have a clear, testable definition of done.