design-audit

name	design-audit
description	Audit and improve an existing design document. Use after a design doc has been drafted to verify technical accuracy, find gaps, and fix issues.

Purpose

Review a design document for correctness, completeness, and consistency, then apply fixes directly to the document.

Process

1. Research

Before evaluating the design, build domain knowledge:

• Search the web for relevant documentation on APIs, behaviors, limits, and best practices that relate to the design.
• Read the project's existing design documents in docs/design/ to understand established patterns and conventions.
• Read relevant source code to verify that types, file paths, and service methods referenced in the design actually exist or are plausible extensions of the current architecture.

2. Evaluate

Check the design for:

• Factual accuracy: Do behaviors described in the design match actual documentation and API semantics? Are limits, default values, and semantics correct?
• Internal consistency: Do the CX examples match the technical design? Do error messages reference the right names and types? Do file change lists cover all sections that describe modifications?
• Completeness: Are all validation rules specified? Are error messages provided for every failure case? Does the testing strategy cover the described behaviors?
• Sharp edges: Are there edge cases not addressed? Race conditions? Conflicting behaviors with existing features? Ambiguous specifications that could be interpreted multiple ways?
• Underspecification: Are there sections that say "TBD" or leave decisions open that should be resolved? Are default values specified? Are boundary conditions defined?
• Test specificity risk: For each test scenario in the testing strategy, consider whether the same observable result could be produced by a different code path (e.g., pattern resolution vs PK pool assignment). If so, add a note to the test scenario flagging the risk — not as an error in the design, but as guidance to the task worker that it may need to adjust the test after writing and running it to ensure it targets the correct behavior. Example note: "⚠ This test's expected output could also be produced by [alternative path]. The implementing agent should verify the test exercises [intended path] and adjust assertions or test setup if needed."

3. Fix

Apply corrections directly to the design document:

• Fix factual errors with correct information from documentation.
• Resolve inconsistencies by making the document internally coherent.
• Add missing validation rules, error messages, or edge case handling.
• Clarify ambiguous specifications with concrete decisions.
• Move genuinely open questions to the Open Questions section rather than leaving them inline.
• Do not remove content that is correct; only add, clarify, or correct.

4. Summary

After making changes, provide a brief summary of what was found and fixed. Do not write a long report — just list the key issues addressed.