// Validate a pull request against the Trinity development methodology and generate a merge decision report.
Generate and update user documentation from code, feature flows, and recent changes into docs/user-docs/
Detect drift between architecture.md and the actual code. Validates 15 architectural invariants and flags stale doc claims with suggested edits.
Validate config hygiene — docker-compose env vars vs .env.example vs code references vs architecture docs. Flags missing, stale, or undocumented configuration.
Validate database schema consistency — DDL in schema.py vs migrations.py vs architecture.md. Flags drift between the three sources of truth.
Chief Security Officer audit — infrastructure-first security scan with secrets archaeology, dependency supply chain, CI/CD pipeline, LLM/AI security, OWASP Top 10, STRIDE threat modeling, and active verification. Two modes — daily (8/10 confidence gate) and comprehensive (2/10 bar).
Run the Playwright frontend e2e suite against a live Trinity stack, analyze failures, and update visual regression snapshots. Use after UI changes, before merging a PR with the `ui` label, or when the `frontend-e2e` CI workflow fails.
| name | validate-pr |
| description | Validate a pull request against the Trinity development methodology and generate a merge decision report. |
| allowed-tools | ["Bash","Read","Grep"] |
| user-invocable | true |
| argument-hint | <pr-number-or-url> |
| automation | gated |
Validate a pull request against the Trinity development methodology and generate a merge decision report.
| Source | Location | Read | Write | Description |
|---|---|---|---|---|
| PR Details | GitHub API | ✅ | PR metadata and diff | |
| Requirements | docs/memory/requirements.md | ✅ | Req updates | |
| Architecture | docs/memory/architecture.md | ✅ | API changes | |
| Feature Flows | docs/memory/feature-flows/ | ✅ | Flow updates | |
| GitHub Issues | abilityai/trinity | ✅ | Issue references |
/validate-pr <pr-number-or-url>
Before deep validation, check the basics:
Fixes #N or Closes #N in title or body)gh pr view $PR_NUMBER --json title,body,labels | jq '{title: .title, body: .body[:300]}'
If the PR has no issue link, flag as ❌ CRITICAL immediately.
# Get PR number from argument (extract from URL if needed)
PR_NUMBER=<extract number from argument>
# Fetch PR details
gh pr view $PR_NUMBER --json title,body,author,baseRefName,headRefName,files,additions,deletions,changedFiles
# Get list of changed files
gh pr diff $PR_NUMBER --name-only
# Get the actual diff for analysis
gh pr diff $PR_NUMBER
Store this information for validation:
Verify baseRefName is dev (unless this is a release-cut PR from dev → main):
dev (not main directly, unless it's a release PR)main: flag as ❌ CRITICAL unless PR title/body indicates a release cutchangedFiles >= 50: flag as ⚠️ WARNING — "Large PR, consider splitting"Check that commits on the branch have descriptive messages:
gh pr view $PR_NUMBER --json commits --jq '.commits[].messageHeadline'
Check if PR references a GitHub Issue (e.g., "Closes #17", "Fixes #23").
Required if:
Validation:
Check if docs/memory/requirements.md is in the changed files list.
Required if:
Validation:
Check if docs/memory/architecture.md is in the changed files list.
Required if PR modifies:
Validation:
Look for files matching docs/memory/feature-flows/*.md in changed files.
Analyze the code changes to determine if they modify feature behavior:
If behavior changed but no feature flow updated: Flag as ⚠️ WARNING - "Feature behavior changed, flow may need update"
For each changed feature flow file, verify structure:
Required Sections (check headings exist):
## Overview - One-line description## User Story - As a [user], I want to [action]...## Entry Points - UI and API entry points## Frontend Layer - Components, State Management, API Calls## Backend Layer - Endpoint, Business Logic, Database Operations## Side Effects - Events, logs, notifications## Error Handling - Error cases table## Security Considerations - Auth, validation, rate limiting## Testing - Prerequisites, Test Steps, Edge Cases, Status## Related Flows - Upstream/downstream connectionsFormat Requirements:
src/file.py:123If new feature flow added, check docs/memory/feature-flows.md:
Run security checks on the PR diff:
# Get the full diff
gh pr diff $PR_NUMBER > /tmp/pr_diff.txt
grep -iE '(sk-[a-zA-Z0-9]{20,}|pk-[a-zA-Z0-9]{20,}|ghp_[a-zA-Z0-9]{36}|gho_[a-zA-Z0-9]{36}|github_pat_[a-zA-Z0-9]{22,}|xox[baprs]-[a-zA-Z0-9-]{10,}|ya29\.[a-zA-Z0-9_-]{50,}|AIza[a-zA-Z0-9_-]{35}|AKIA[A-Z0-9]{16})' /tmp/pr_diff.txt
grep -oE '[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}' /tmp/pr_diff.txt | grep -vE '(example\.com|example\.org|placeholder|test@|user@example|noreply@|anthropic\.com)'
grep -oE '\b([0-9]{1,3}\.){3}[0-9]{1,3}\b' /tmp/pr_diff.txt | grep -vE '^(127\.|0\.0\.0\.0|172\.(1[6-9]|2[0-9]|3[0-1])\.|192\.168\.|10\.)'
gh pr diff $PR_NUMBER --name-only | grep -E '^\.env$|/\.env$' | grep -v '\.example'
grep -iE '(password|secret|token|api_key|apikey|auth_token|access_token|private_key)\s*[=:]\s*["\x27][^"\x27]{8,}["\x27]' /tmp/pr_diff.txt | grep -vE '(process\.env|os\.environ|os\.getenv|\$\{|example|placeholder|your-|changeme|xxx|\\$\\{)'
gh pr diff $PR_NUMBER --name-only | grep -iE '(credentials\.json|service.?account.*\.json|\.pem$|\.key$|id_rsa|id_ed25519|\.p12$|\.pfx$|htpasswd)'
Review the diff scope:
Spot-check changed code against existing patterns:
Check PR description and changed files:
Create the report in this format:
PR: #[number] - [title] Author: [author] Branch: [head] → [base] Files Changed: [count] (+[additions]/-[deletions])
| Category | Status | Notes |
|---|---|---|
| Commit Messages | ✅/❌ | [details] |
| Base Branch | ✅/❌ | targets dev (or release cut to main) |
| PR Size | ✅/⚠️ | [file count] |
| Roadmap | ✅/❌/➖ | [details or N/A] |
| Requirements | ✅/❌/➖ | [details or N/A] |
| Architecture | ✅/❌/➖ | [details or N/A] |
| Feature Flows | ✅/❌/⚠️ | [details] |
| Feature Flow Format | ✅/❌/➖ | [details or N/A] |
| Security Check | ✅/❌ | [details] |
| Code Quality | ✅/⚠️ | [details] |
| Requirements Trace | ✅/⚠️ | [details] |
[APPROVE / REQUEST CHANGES / NEEDS DISCUSSION]
[Brief justification for the recommendation]
If REQUEST CHANGES, comment template:
This PR requires the following changes before merge:
- [ ] [Required change 1]
- [ ] [Required change 2]
...
Please address these items and request re-review.
| Icon | Meaning |
|---|---|
| ✅ | Passed - meets requirements |
| ❌ | Failed - must be fixed before merge |
| ⚠️ | Warning - needs human review |
| ➖ | Not applicable to this PR |
| Change Type | Required Docs |
|---|---|
| Bug fix | Descriptive commit message only |
| Feature / API change | Architecture or feature-flow as needed |
| New capability | Requirements + feature-flow |
| Refactor | Descriptive commit message only (unless it changes architecture) |
| Docs only | No additional docs needed |
docs/DEVELOPMENT_WORKFLOW.md - Development cycle and reviewer pipelinedocs/memory/feature-flows.md - Feature flow index/review - Complementary code review (SQL safety, race conditions, auth, scope drift, test gaps)/cso --diff - Deep security audit (required for P0/P1 features)| PR Type | /review | /validate-pr | /cso --diff |
|---|---|---|---|
| Feature (P0/P1) | Required | Required | Required |
| Feature (P2/P3) | Required | Required | Recommended |
| Bug fix | Required | Required | Skip (unless auth/security) |
| Refactor | Required | Required | Skip |
| Docs only | Skip | Required | Skip |