metabuilder/docs/reference/TEAM_CHECKLIST.md

📋 Team Implementation Checklist

Phase 1: Setup & Understanding (Day 1)

• Read REFACTORING_QUICK_START.md (15 mins)
• Read docs/REFACTORING_ENFORCEMENT_GUIDE.md (30 mins)
• Run npx tsx /workspaces/metabuilder/scripts/enforce-size-limits.ts (5 mins)
• Review the refactored example: src/components/GitHubActionsFetcher.refactored.tsx
• Check available hooks in src/hooks/index.ts
• Share findings with team in standup

Phase 2: Individual Development (Ongoing)

Before Writing Code

• Check if a similar component exists in src/components/
• Check if a similar hook exists in src/hooks/
• Plan component size (estimate LOC)
• Identify what needs to be in hook vs component

During Development

• Keep components under 150 LOC
• Keep hooks under 100 LOC
• Use existing hooks when possible
• Extract business logic to hooks early
• Avoid deeply nested JSX (max 3 levels)
• Use TypeScript for type safety

Before Committing

• Run size limit check locally: npx tsx /workspaces/metabuilder/scripts/enforce-size-limits.ts
• Verify all new files pass checks
• Run linter: npm run lint
• Run tests: npm run test

Phase 3: Code Review (Pull Request)

For PR Author

• Fill PR description with what changed
• Reference related issues
• List any breaking changes
• Include screenshot/demo if UI changes
• Wait for GitHub Actions to pass

For PR Reviewer

• Check GitHub Actions passed (size limits, tests, linting)
• Review component structure
• Verify hooks are reusable
• Check for code duplication
• Verify TypeScript is correct
• Look for missed refactoring opportunities
• Run locally and test if needed

Phase 4: Merge & Deployment

• All checks pass (GitHub Actions)
• At least 1 approval from maintainer
• Merge to main branch
• Deploy to staging (if applicable)
• Monitor for errors
• Deploy to production (if applicable)

Phase 5: Large Component Refactoring

For each large component (>150 LOC):

Planning (30 mins)

• Identify all component responsibilities
• List all useState/useRef/useContext hooks
• Identify API calls
• Identify side effects (useEffect)
• Sketch out new hook structure
• Sketch out component tree

Hook Creation (1-2 hours)

• Create new hook file in src/hooks/
• Move non-rendering logic to hook
• Create interfaces for data structures
• Export hook and types
• Add JSDoc comments
• Keep hook under 100 LOC

Component Decomposition (2-3 hours)

• Create child component files
• Move rendering to child components
• Each component under 150 LOC
• Pass data via props
• Handle callbacks via props

Integration (1 hour)

• Create container component
• Use hook to get data
• Compose child components
• Wire user interactions
• Keep under 150 LOC

Testing (1-2 hours)

• Write unit tests for hook
• Write component tests
• Test integration between parts
• Test error scenarios
• Verify old functionality preserved

Verification (30 mins)

• Run size limit check
• Run linter
• Run tests
• Manual testing in browser
• Commit and push

Maintenance Tasks

Weekly

• Review size limits report
• Check for new violations
• Review PRs for size violations
• Answer team questions

Monthly

• Audit hook reusability
• Look for duplicate hooks
• Update documentation if needed
• Review and update guidelines

Quarterly

• Analyze codebase health metrics
• Plan next refactoring phase
• Update refactoring strategy
• Share learnings with team

Common Scenarios

Scenario: Component exceeds 150 LOC

1. Analyze why (too many responsibilities?)
2. Extract logic to hook
3. Break rendering into child components
4. Create container to wire together
5. Re-run size limit check
6. → Usually drops to 80-100 LOC

Scenario: Hook exceeds 100 LOC

1. Analyze what the hook does
2. Look for sub-responsibilities
3. Break into multiple smaller hooks
4. Have main hook use other hooks
5. Export main hook
6. → Easier to test and reuse

Scenario: Child component still too large

1. Check if it has multiple responsibilities
2. Extract state management to hook
3. Break rendering further
4. Consider if it should be a container + multiple UI components
5. Re-run size limit check

Scenario: Duplicate code in multiple files

1. Extract to custom hook
2. Both files import and use hook
3. Remove duplicate code
4. Test both locations still work
5. → Better maintainability

Success Stories

Example 1: GitHubActionsFetcher

Before: 887 LOC (monolithic) After:

• useGitHubFetcher.ts: 65 LOC
• useAutoRefresh.ts: 48 LOC
• GitHubActionsFetcher.tsx: 85 LOC
• WorkflowRunCard.tsx: 48 LOC
• WorkflowRunStatus.tsx: 28 LOC Total: ~275 LOC (69% reduction) Benefits: More reusable, easier to test, easier to maintain

Example 2: Form Component (Hypothetical)

Before: 350 LOC (mixed concerns) After:

• useForm.ts: 80 LOC (handles validation, submission)
• useFormField.ts: 50 LOC (per-field logic)
• FormComponent.tsx: 120 LOC (renders form)
• FormField.tsx: 40 LOC (single field)
• FormActions.tsx: 30 LOC (buttons) Total: ~320 LOC (9% reduction, much better structure) Benefits: Form hook reusable in multiple contexts

Resources & Links

Quick Start

• REFACTORING_QUICK_START.md - Start here!
• ARCHITECTURE_DIAGRAM.md - Visual explanations

Detailed Guides

• docs/REFACTORING_ENFORCEMENT_GUIDE.md - Full reference
• docs/REFACTORING_QUICK_REFERENCE.md - Code examples
• docs/REFACTORING_STRATEGY.md - Deep dive

Code Examples

• src/components/GitHubActionsFetcher.refactored.tsx - Good example
• src/hooks/useGitHubFetcher.ts - Hook example
• src/components/WorkflowRunCard.tsx - Small component example

Tools

• scripts/enforce-size-limits.ts - Size limit checker
• .github/workflows/size-limits.yml - CI/CD automation
• .git/hooks/pre-commit - Local enforcement

FAQ - Team Questions

Q: What if my component genuinely needs to be >150 LOC? A: Rare. Usually indicates multiple responsibilities. Try harder to decompose. Discuss with team lead if truly unavoidable.

Q: Can I create a component just to hold state for child components? A: Yes! That's a "container component". The container handles logic/state, children handle rendering. Both stay under limits.

Q: What if the hook and component are tightly coupled? A: That's fine. Many components have a corresponding hook (e.g., useMyForm + MyForm). Just keep both small and focused.

Q: Should I test my hooks? A: Yes! Hooks are logic, components are rendering. Test logic separately. Use renderHook from React Testing Library.

Q: What about styled-components / CSS modules? A: They don't count toward LOC limits (they're in separate files). Focus on TypeScript/TSX LOC only.

Q: How do I handle complex state? A: Use custom hooks! Complex state management → custom hook. Makes it testable and reusable.

Q: What if I need lots of props? A: If >5 props, consider:

1. Group related props into objects
2. Move some logic to container
3. Create multiple components instead of one mega-component

Q: Can I import from my own hooks? A: Yes! Hooks can use other hooks. Example: useForm can use useFormValidation.

---

Sign-Off

• I have read and understand these guidelines
• I commit to following these practices
• I will help others follow these practices
• I will report size limit violations

Name & Date: __________________________ , ______________

---

Last Updated: December 25, 2025 Version: 1.0 Status: 🟢 Active