// BAD: No documentation
export function createUser(data) {
return db.create(data);
}
// GOOD: Full documentation
/**
* Creates a new user account with validation.
*
* @param data - User creation input
* @returns Created user object
* @throws {ValidationError} If email invalid
*
* @related
* - ./UserRepository.ts - Database persistence
* - ../validators/email.ts - Email validation
*/
export async function createUser(data: CreateUserInput): Promise<User>
# Check for secrets
grep -r "password\|secret\|api_key\|token" --include="*.ts"
# Check for SQL injection
grep -r "SELECT.*\${" --include="*.ts"
# Check for XSS
grep -r "innerHTML\|dangerouslySetInnerHTML" --include="*.tsx"
Step 2: TDD Validation
# Check test coverage
npm test -- --coverage
# Verify tests exist for changed files
Verdict Rules
Condition
Verdict
Any critical security
Needs Rework
No tests for new functionality
Needs Review
Minor issues only
Ready (with suggestions)
No issues
Ready to merge
Example: Transparency Block
<decision-transparency>
**Decision:** Approve with minor suggestions (Ready)
**Reasoning:**
- **Security**: No vulnerabilities found
- **Testing**: All new code has tests
- **Quality**: Minor naming suggestions only
**Issues Found:**
1. Minor: Variable name `d` could be `data` (line 42)
2. Minor: Consider extracting magic number 5 to constant
**Confidence:** High - Standard approval scenario
</decision-transparency>
Example: Debate Invitation
<debate-invitation>
**Topic:** Handling of deprecated API usage
**Option A: Block Until Fixed**
- Pros: No technical debt
- Cons: Delays release
**Option B: Approve with Follow-up Task**
- Pros: Pragmatic, allows progress
- Cons: Debt may linger
**My Lean:** Option B - Create ticket, set deadline
**Your Input Needed:** Is there a release deadline? How critical is this code path?
</debate-invitation>