Skip to content

notque/vexjoy-agent / skills/review/review

Code review: systematic single-file, parallel multi-reviewer, full-repo audit, PR diff review.

FileKindSize
SKILL.mdskill md11.7 KB
references/architecture-smell-baseline.mdmarkdown6.8 KB
references/audit-playbook.mdmarkdown10.2 KB
references/disprove-pass.mdmarkdown2.3 KB
references/go-review-patterns.mdmarkdown4.0 KB
references/receiving-feedback.mdmarkdown3.0 KB
references/report-template.mdmarkdown1.9 KB
references/reviewer-code.mdmarkdown6.2 KB
references/reviewer-code/code-quality.mdmarkdown4.6 KB
references/reviewer-code/comments.mdmarkdown3.6 KB
references/reviewer-code/config-safety.mdmarkdown3.7 KB
references/reviewer-code/dead-code.mdmarkdown3.2 KB
references/reviewer-code/language-checks.mdmarkdown6.7 KB
references/reviewer-code/language-specialist.mdmarkdown4.7 KB
references/reviewer-code/naming.mdmarkdown3.3 KB
references/reviewer-code/performance.mdmarkdown3.5 KB
references/reviewer-code/simplifier.mdmarkdown5.3 KB
references/reviewer-code/test-analyzer.mdmarkdown4.5 KB
references/reviewer-code/type-design.mdmarkdown4.0 KB
references/reviewer-domain.mdmarkdown9.1 KB
references/reviewer-domain/adr-compliance.mdmarkdown3.0 KB
references/reviewer-domain/business-logic.mdmarkdown4.6 KB
references/reviewer-domain/common-bugs.mdmarkdown6.7 KB
references/reviewer-domain/edge-case-tables.mdmarkdown4.5 KB
references/reviewer-domain/operational-preferred-patterns.mdmarkdown7.2 KB
references/reviewer-domain/pragmatic-builder.mdmarkdown4.2 KB
references/reviewer-domain/production-gaps.mdmarkdown5.3 KB
references/reviewer-domain/sapcc-structural.mdmarkdown5.4 KB
references/reviewer-domain/state-machine-verification.mdmarkdown5.2 KB
references/reviewer-domain/structural-categories.mdmarkdown5.8 KB
references/reviewer-perspectives.mdmarkdown8.0 KB
references/reviewer-perspectives/clarity-and-assumption-detection.mdmarkdown4.8 KB
references/reviewer-perspectives/code-review-detection.mdmarkdown4.4 KB
references/reviewer-perspectives/contrarian.mdmarkdown2.3 KB
references/reviewer-perspectives/meta-process.mdmarkdown2.7 KB
references/reviewer-perspectives/newcomer.mdmarkdown2.0 KB
references/reviewer-perspectives/pedant.mdmarkdown3.3 KB
references/reviewer-perspectives/review-detection-commands.mdmarkdown8.7 KB
references/reviewer-perspectives/skeptical-senior.mdmarkdown2.9 KB
references/reviewer-perspectives/user-advocate.mdmarkdown2.9 KB
references/reviewer-system.mdmarkdown14.0 KB
references/reviewer-system/api-contract.mdmarkdown3.4 KB
references/reviewer-system/compliance-checklists.mdmarkdown5.1 KB
references/reviewer-system/concurrency.mdmarkdown3.6 KB
references/reviewer-system/dependency-audit.mdmarkdown3.3 KB
references/reviewer-system/docs-validator.mdmarkdown4.0 KB
references/reviewer-system/error-messages.mdmarkdown3.1 KB
references/reviewer-system/financial-resilience-de-eu.mdmarkdown5.3 KB
references/reviewer-system/german-it-security.mdmarkdown10.7 KB
references/reviewer-system/industry-specific-compliance.mdmarkdown3.5 KB
references/reviewer-system/migration-safety.mdmarkdown3.3 KB
references/reviewer-system/observability.mdmarkdown3.1 KB
references/reviewer-system/security-authz.mdmarkdown9.0 KB
references/reviewer-system/security-ci-cd.mdmarkdown7.6 KB
references/reviewer-system/security-data-exfil.mdmarkdown9.5 KB
references/reviewer-system/security-finding-template.mdmarkdown3.0 KB
references/reviewer-system/security-injection.mdmarkdown6.3 KB
references/reviewer-system/security-pii.mdmarkdown7.3 KB
references/reviewer-system/security.mdmarkdown3.6 KB
references/reviewer-system/silent-failures.mdmarkdown3.6 KB
references/reviewer-system/sovereign-cloud-data-residency.mdmarkdown6.6 KB
references/reviewer-system/stride-threat-model.mdmarkdown3.2 KB

references/reviewer-domain/state-machine-verification.md

View on GitHub
# State Machine Verification

Review methodologies for state machines and stateful business logic.

## Review Checklist

### 1. State Enumeration
- [ ] All valid states documented
- [ ] Initial and terminal states identified
- [ ] Error/failure states identified

### 2. Transition Validation
- [ ] All valid transitions documented
- [ ] Invalid transitions explicitly rejected
- [ ] Guards/conditions specified
- [ ] Terminal states cannot exit

### 3. Concurrent Access
- [ ] State changes atomic
- [ ] Race conditions prevented
- [ ] Lock ordering prevents deadlock

### 4. Error Handling
- [ ] Error states have recovery paths
- [ ] Timeout handling specified
- [ ] Retry logic is idempotent

## Patterns

### Basic State Machine
```go
type OrderStatus string

const (
    OrderPending   OrderStatus = "pending"
    OrderPaid      OrderStatus = "paid"
    OrderShipped   OrderStatus = "shipped"
    OrderDelivered OrderStatus = "delivered"
    OrderCancelled OrderStatus = "cancelled"
)

// Valid: pending->paid->shipped->delivered, pending/paid->cancelled
func (o *Order) SetStatus(newStatus OrderStatus) error {
    switch o.Status {
    case OrderPending:
        if newStatus != OrderPaid && newStatus != OrderCancelled {
            return ErrInvalidTransition
        }
    case OrderPaid:
        if newStatus != OrderShipped && newStatus != OrderCancelled {
            return ErrInvalidTransition
        }
    case OrderShipped:
        if newStatus != OrderDelivered {
            return ErrInvalidTransition
        }
    case OrderDelivered, OrderCancelled:
        return ErrTerminalState
    default:
        return ErrUnknownStatus
    }
    o.Status = newStatus
    return nil
}
```

### State Machine with Guards
```go
func (t *Task) Start() error {
    if t.Status != TaskAssigned {
        return fmt.Errorf("cannot start task in status: %s", t.Status)
    }
    if t.Assignee == nil {
        return ErrNoAssignee
    }
    t.Status = TaskInProgress
    return nil
}
```

### State Machine with Timeout
```go
func (s *Session) Refresh() error {
    if s.Status != SessionActive {
        return ErrSessionNotActive
    }
    if s.IsExpired() {
        s.Status = SessionExpired
        return ErrSessionExpired
    }
    s.ExpiresAt = time.Now().Add(SessionTimeout)
    return nil
}
```

## Common Bugs

### Missing Transition Validation
```go
// BUG: Any transition allowed
func (o *Order) SetStatus(status OrderStatus) { o.Status = status }
// FIX: Validate transitions
func (o *Order) SetStatus(status OrderStatus) error {
    if !o.IsValidTransition(o.Status, status) { return ErrInvalidTransition }
    o.Status = status
    return nil
}
```

### Terminal States Escapable
```go
// BUG: Can modify completed order
func (o *Order) AddItem(item Item) { o.Items = append(o.Items, item) }
// FIX:
func (o *Order) AddItem(item Item) error {
    if o.Status == OrderCompleted || o.Status == OrderCancelled { return ErrOrderClosed }
    o.Items = append(o.Items, item)
    return nil
}
```

### Race Condition on State Change
```go
// BUG: Check-then-act race
if order.Status == "pending" { order.Status = "paid"; db.Save(order) }
// FIX: Atomic update
result := db.Exec("UPDATE orders SET status = ? WHERE id = ? AND status = ?",
    "paid", order.ID, "pending")
if result.RowsAffected == 0 { return ErrConcurrentModification }
```

### No Timeout Handling
```go
// BUG: Session never expires — no ExpiresAt field
// FIX: Add ExpiresAt, check in methods
func (s *Session) CheckExpiration() {
    if time.Now().After(s.ExpiresAt) && s.Status == SessionActive {
        s.Status = SessionExpired
    }
}
```

## State Transition Tables

### Order
| From | To | Valid? | Condition |
|------|-----|--------|-----------|
| pending | paid | Y | Payment successful |
| pending | cancelled | Y | User cancels |
| paid | shipped | Y | Dispatched |
| paid | cancelled | Y | Cancel before shipping |
| shipped | delivered | Y | Delivery confirmed |
| shipped | cancelled | N | Cannot cancel after shipment |
| delivered | any | N | Terminal |
| cancelled | any | N | Terminal |

### Task
| From | To | Valid? | Condition |
|------|-----|--------|-----------|
| pending | assigned | Y | Assignee set |
| assigned | in_progress | Y | User starts |
| assigned | pending | Y | Assignee removed |
| in_progress | completed | Y | Result provided |
| in_progress | failed | Y | Error occurred |
| completed | any | N | Terminal |
| failed | pending | Y | Retry allowed |

## Review Questions

1. **States**: All documented? Initial/terminal clear?
2. **Transitions**: Validation function? Invalid rejected with clear errors?
3. **Guards**: Preconditions checked before change? Failure handled?
4. **Concurrency**: Atomic? Race possible? Lock ordering?
5. **Errors**: Recovery path? Rollback mechanism?
6. **Persistence**: When persisted? What if persistence fails? Validation before or after?

## Code Review Template

```markdown
### State Machine: [Component]
**States**: [list] | Initial: [x] | Terminal: [x] | Error: [x]

**Transitions Verified:**
- [FROM] -> [TO]: [condition] Y/N

**Issues Found:**
1. **[Issue]** - `file.go:line` — [problem]. Impact: [what it allows]. Fix: [recommendation].

**Terminal Enforcement:** Y/N
**Concurrent Safety:** Y/N
**Timeout Handling:** Y/N
**Error Recovery:** Y/N
```
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall