Add userDismissedAt field to agents schema
This commit is contained in:
Lukas May
263
docs/deviation-rules.md
Normal file
263
docs/deviation-rules.md
Normal file
@@ -0,0 +1,263 @@
|
||||
# Deviation Rules
|
||||
|
||||
During execution, agents discover work not in the original plan. These rules define how to handle deviations **automatically, without asking for permission** (except Rule 4).
|
||||
|
||||
## The Four Rules
|
||||
|
||||
### Rule 1: Auto-Fix Bugs
|
||||
**No permission needed.**
|
||||
|
||||
Fix immediately when encountering:
|
||||
- Broken code (syntax errors, runtime errors)
|
||||
- Logic errors (wrong conditions, off-by-one)
|
||||
- Security issues (injection vulnerabilities, exposed secrets)
|
||||
- Type errors (TypeScript violations)
|
||||
|
||||
```yaml
|
||||
deviation:
|
||||
rule: 1
|
||||
type: bug_fix
|
||||
description: "Fixed null reference in user lookup"
|
||||
location: src/services/auth.ts:45
|
||||
original_code: "user.email.toLowerCase()"
|
||||
fixed_code: "user?.email?.toLowerCase() ?? ''"
|
||||
reason: "Crashes when user not found"
|
||||
```
|
||||
|
||||
### Rule 2: Auto-Add Missing Critical Functionality
|
||||
**No permission needed.**
|
||||
|
||||
Add immediately when clearly required:
|
||||
- Error handling (try/catch for external calls)
|
||||
- Input validation (user input, API boundaries)
|
||||
- Authentication checks (protected routes)
|
||||
- CSRF protection
|
||||
- Rate limiting (if pattern exists in codebase)
|
||||
|
||||
```yaml
|
||||
deviation:
|
||||
rule: 2
|
||||
type: missing_critical
|
||||
description: "Added input validation to createUser"
|
||||
location: src/api/users.ts:23
|
||||
added: "Zod schema validation for email, password length"
|
||||
reason: "API accepts any input without validation"
|
||||
```
|
||||
|
||||
### Rule 3: Auto-Fix Blocking Issues
|
||||
**No permission needed.**
|
||||
|
||||
Fix immediately when blocking task completion:
|
||||
- Missing dependencies (npm install)
|
||||
- Broken imports (wrong paths, missing exports)
|
||||
- Configuration errors (env vars, tsconfig)
|
||||
- Build failures (compilation errors)
|
||||
|
||||
```yaml
|
||||
deviation:
|
||||
rule: 3
|
||||
type: blocking_issue
|
||||
description: "Added missing zod dependency"
|
||||
command: "npm install zod"
|
||||
reason: "Import fails without package"
|
||||
```
|
||||
|
||||
### Rule 4: ASK About Architectural Changes
|
||||
**Permission required.**
|
||||
|
||||
Stop and ask user before:
|
||||
- New database tables or major schema changes
|
||||
- New services or major component additions
|
||||
- Changes to API contracts
|
||||
- New external dependencies (beyond obvious needs)
|
||||
- Authentication/authorization model changes
|
||||
|
||||
```yaml
|
||||
deviation:
|
||||
rule: 4
|
||||
type: architectural_change
|
||||
status: PENDING_APPROVAL
|
||||
description: "Considering adding Redis for session storage"
|
||||
current: "Sessions stored in SQLite"
|
||||
proposed: "Redis for distributed session storage"
|
||||
reason: "Multiple server instances need shared sessions"
|
||||
question: "Should we add Redis, or use sticky sessions instead?"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Decision Tree
|
||||
|
||||
```
|
||||
Encountered unexpected issue
|
||||
│
|
||||
▼
|
||||
Is it broken code?
|
||||
(errors, bugs, security)
|
||||
│
|
||||
YES ─┴─ NO
|
||||
│ │
|
||||
▼ ▼
|
||||
Rule 1 Is critical functionality missing?
|
||||
Auto-fix (validation, auth, error handling)
|
||||
│
|
||||
YES ─┴─ NO
|
||||
│ │
|
||||
▼ ▼
|
||||
Rule 2 Is it blocking task completion?
|
||||
Auto-add (deps, imports, config)
|
||||
│
|
||||
YES ─┴─ NO
|
||||
│ │
|
||||
▼ ▼
|
||||
Rule 3 Is it architectural?
|
||||
Auto-fix (tables, services, contracts)
|
||||
│
|
||||
YES ─┴─ NO
|
||||
│ │
|
||||
▼ ▼
|
||||
Rule 4 Ignore or note
|
||||
ASK for future
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Documentation Requirements
|
||||
|
||||
All deviations MUST be documented in SUMMARY.md:
|
||||
|
||||
```yaml
|
||||
# 2-3-SUMMARY.md
|
||||
phase: 2
|
||||
plan: 3
|
||||
|
||||
deviations:
|
||||
- rule: 1
|
||||
type: bug_fix
|
||||
description: "Fixed null reference in auth service"
|
||||
location: src/services/auth.ts:45
|
||||
|
||||
- rule: 2
|
||||
type: missing_critical
|
||||
description: "Added Zod validation to user API"
|
||||
location: src/api/users.ts:23-45
|
||||
|
||||
- rule: 3
|
||||
type: blocking_issue
|
||||
description: "Installed missing jose dependency"
|
||||
command: "npm install jose"
|
||||
|
||||
- rule: 4
|
||||
type: architectural_change
|
||||
status: APPROVED
|
||||
description: "Added refresh_tokens table"
|
||||
approved_by: user
|
||||
approved_at: 2024-01-15T10:30:00Z
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Deviation Tracking in Tasks
|
||||
|
||||
When a deviation is significant, create tracking:
|
||||
|
||||
### Minor Deviations
|
||||
Log in SUMMARY.md, no separate task.
|
||||
|
||||
### Major Deviations (Rule 4)
|
||||
Create a decision record:
|
||||
|
||||
```sql
|
||||
INSERT INTO task_history (
|
||||
task_id,
|
||||
field,
|
||||
old_value,
|
||||
new_value,
|
||||
changed_by
|
||||
) VALUES (
|
||||
'current-task-id',
|
||||
'deviation',
|
||||
NULL,
|
||||
'{"rule": 4, "description": "Added Redis", "approved": true}',
|
||||
'worker-123'
|
||||
);
|
||||
```
|
||||
|
||||
### Deviations That Spawn Work
|
||||
If fixing a deviation requires substantial work:
|
||||
|
||||
1. Complete current task
|
||||
2. Create new task for deviation work
|
||||
3. Link new task as dependency if blocking
|
||||
4. Continue with original plan
|
||||
|
||||
---
|
||||
|
||||
## Examples by Category
|
||||
|
||||
### Rule 1: Bug Fixes
|
||||
|
||||
| Issue | Fix | Documentation |
|
||||
|-------|-----|---------------|
|
||||
| Undefined property access | Add optional chaining | Note in summary |
|
||||
| SQL injection vulnerability | Use parameterized query | Note + security flag |
|
||||
| Race condition in async code | Add proper await | Note in summary |
|
||||
| Incorrect error message | Fix message text | Note in summary |
|
||||
|
||||
### Rule 2: Missing Critical
|
||||
|
||||
| Gap | Addition | Documentation |
|
||||
|-----|----------|---------------|
|
||||
| No input validation | Add Zod/Yup schema | Note in summary |
|
||||
| No error handling | Add try/catch + logging | Note in summary |
|
||||
| No auth check | Add middleware | Note in summary |
|
||||
| No CSRF token | Add csrf protection | Note + security flag |
|
||||
|
||||
### Rule 3: Blocking Issues
|
||||
|
||||
| Blocker | Resolution | Documentation |
|
||||
|---------|------------|---------------|
|
||||
| Missing npm package | npm install | Note in summary |
|
||||
| Wrong import path | Fix path | Note in summary |
|
||||
| Missing env var | Add to .env.example | Note in summary |
|
||||
| TypeScript config issue | Fix tsconfig | Note in summary |
|
||||
|
||||
### Rule 4: Architectural (ASK FIRST)
|
||||
|
||||
| Change | Why Ask | Question Format |
|
||||
|--------|---------|-----------------|
|
||||
| New DB table | Schema is contract | "Need users_sessions table. Create it?" |
|
||||
| New service | Architectural decision | "Extract auth to separate service?" |
|
||||
| API contract change | Breaking change | "Change POST /users response format?" |
|
||||
| New external dep | Maintenance burden | "Add Redis for caching?" |
|
||||
|
||||
---
|
||||
|
||||
## Integration with Verification
|
||||
|
||||
Deviations are inputs to verification:
|
||||
|
||||
1. **Verifier loads SUMMARY.md** with deviation list
|
||||
2. **Bug fixes (Rule 1)** verify the fix doesn't break tests
|
||||
3. **Critical additions (Rule 2)** verify they're properly integrated
|
||||
4. **Blocking fixes (Rule 3)** verify build/tests pass
|
||||
5. **Architectural changes (Rule 4)** verify they match approved design
|
||||
|
||||
---
|
||||
|
||||
## Escalation Path
|
||||
|
||||
If unsure which rule applies:
|
||||
|
||||
1. **Default to Rule 4** (ask) rather than making wrong assumption
|
||||
2. Document uncertainty in deviation notes
|
||||
3. Include reasoning for why you're asking
|
||||
|
||||
```yaml
|
||||
deviation:
|
||||
rule: 4
|
||||
type: uncertain
|
||||
description: "Adding caching layer to API responses"
|
||||
reason: "Could be Rule 2 (performance is critical) or Rule 4 (new infrastructure)"
|
||||
question: "Is Redis caching appropriate here, or should we use in-memory?"
|
||||
```
|
||||
Reference in New Issue
Block a user