# Ff Review

> Ff Review is an Agent Skill for testing & quality published in the X-GenGroup/Flow-Factory repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Mandatory pre-commit code review gate. Checks constraint violations, cross-module consistency, and implementation quality. Trigger proactively when changes span multiple files or touch shared infrastructure. Trigger: 'review', 'check before commit'.

- Skill name: `ff-review`
- Category: [Testing & Quality](https://www.openparable.com/skill/testing-quality/1)
- Source: https://github.com/X-GenGroup/Flow-Factory/blob/HEAD/.agents/skills/ff-review/SKILL.md
- Repository: X-GenGroup/Flow-Factory (628 GitHub stars when collected)

## SKILL.md

# Code Review Workflow

## Process Overview

```
1. Capture changes → git diff
2. Load constraints → .agents/knowledge/constraints.md
3. Review against constraints and architecture
4. Route by verdict:
   ✓ Safe → Proceed with commit
   ⚠ Needs-attention → Fix issues, then commit
   ✗ Risky → Halt and report
```

## Step 1: Capture Changes

```bash
git diff HEAD          # All changes
git status             # Modified files
```

## Step 2: Load Context

- Read `.agents/knowledge/constraints.md` — All hard constraints
- Reference `.agents/knowledge/architecture.md` — Module dependencies
- Identify which modules are affected by the changes

## Step 3: Review Checklist

### Constraint Compliance
- [ ] No constraint violations found
- [ ] Registry entries updated if classes moved/renamed (#1–4)
- [ ] Pipeline order preserved (#6)
- [ ] Coupled/decoupled paradigm respected (#7)
- [ ] Base class interfaces not broken (#11–13)
- [ ] Config fields synchronized with YAML examples (#15–17)

### Cross-Module Consistency
- [ ] Changes to `abc.py` base classes reflected in ALL subclasses (grpo, grpo-guard, dppo, nft, awm, dgpo, dpo, crd, diffusion-opd)
- [ ] Changes to `hparams/` reflected in ALL example configs
- [ ] Changes to `AdvantageProcessor` compatible with all trainers
- [ ] Registry keys match actual import paths
- [ ] Sample dataclass `_shared_fields` consistent

### Implementation Quality
- [ ] No hardcoded devices (use `self.device` or `accelerator.device`)
- [ ] `@torch.no_grad()` on reward model `__call__`
- [ ] Proper synchronization barriers for distributed code
- [ ] No ZeRO-3 usage
- [ ] Type annotations on public methods

### Code Style
- [ ] Black formatting (`line-length=100`)
- [ ] isort compliance (`profile="black"`)
- [ ] English comments and docstrings
- [ ] Apache 2.0 license header on new files
- [ ] No unnecessary wildcard imports (except `hparams`)
- [ ] **Top-level imports only** (constraint #22) — see that file for the three sanctioned exceptions (optional deps via `try/except ImportError`, backend-gated runtime feature checks like DeepSpeed/FSDP, unresolvable circular imports).

### Documentation
- [ ] `guidance/` docs updated if behavior changed
- [ ] New config fields added to ALL example configs with defaults and `# Options:` comments
- [ ] PR title follows format: `[{modules}] {type}: {description}`

## Step 4: Route by Verdict

### ✓ Safe
No issues found. Proceed with commit.

### ⚠ Needs-Attention
Issues found but fixable:
1. List each issue with file and line
2. Fix identified problems
3. Re-stage and re-review

### ✗ Risky
Potential breaking changes:
1. Halt commit
2. Report findings with severity
3. Await explicit user approval

## After Commit

- Run `black --check src/ && isort --check src/` to confirm formatting compliance.
- Verify PR title follows `[{modules}] {type}: {description}` format.
- If this was a bug fix, follow `topics/fix_patterns.md` archival process.

## Pre-Review Reading

Before reviewing, always read Tier 1: `constraints.md`, `architecture.md`, `philosophy.md`.

Additionally, read based on diff scope:

| Diff touches... | Also read |
|----------------|-----------|
| `models/` | `topics/adapter_conventions.md`, `topics/parity_testing.md` |
| `trainers/` | `topics/train_inference_consistency.md`, `topics/autocast_param_swap.md` |
| `scheduler/` | `topics/train_inference_consistency.md`, `topics/dtype_precision.md` |
| New adapter | `topics/adapter_conventions.md`, `topics/parity_testing.md` |
| dtype/precision | `topics/dtype_precision.md`, `topics/autocast_param_swap.md` |

## Common Issues Found in Review

1. **Registry path stale** — Class moved but registry not updated
2. **Config field renamed** — YAML examples still use old name
3. **New config field not in examples** — Users won't discover it; add with default value and `# Options:` comment
4. **Base class change not propagated** — Subclass override now has wrong signature
5. **Missing `wait_for_everyone()`** — Distributed deadlock risk
6. **Reward shape mismatch** — Pointwise returning wrong batch dim
7. **License header missing** — New files without Apache 2.0 header
8. **Autocast spans a forward** — flat loss / KL ≈ 0 (fp32 master); see #20a / `topics/autocast_param_swap.md`

---

Source: https://www.openparable.com/skill/testing-quality/ff-review (OpenParable). Cite the canonical URL above.
