aiox-core 5.0.3 → 5.0.4

package/pro/squads/design/data/atomic-refactor-rules.md

@@ -1,582 +1,582 @@
-# Atomic Design Refactoring Rules
-
-> Validation rules and best practices for Atomic Design refactoring.
-> Based on 18+ refactored components with 91% average reduction.
->
-> **v2.0 - Jan/2026:** Adicionados gates anti-over-engineering após análise mostrar +111% código em alguns casos.
-
----
-
-## ⛔ GATES ANTI-OVER-ENGINEERING (LER PRIMEIRO!)
-
-> **LIÇÃO JAN/2026:** Atomizamos 22 componentes. Em alguns casos, FragmentsTab foi de 475 → 1003 linhas (+111%) com 73% dos hooks sem reuso externo.
-
-### GATE 0: Devo Atomizar?
-
-| Linhas | useState | Decisão |
-|--------|----------|---------|
-| >800 | qualquer | **SIM** - atomizar |
-| 500-800 | >7 | **SIM** - atomizar |
-| 500-800 | ≤7 | **TALVEZ** - só se hooks serão reusados |
-| <500 | qualquer | **NÃO** - organizar inline |
-
-### GATE 1: Antes de Criar Cada Hook
-
-```
-PERGUNTA OBRIGATÓRIA: Esse hook será usado em OUTRO componente?
-
-SE SIM → criar o hook (listar onde será usado)
-SE NÃO → NÃO criar, manter useState inline com comentários organizados
-```
-
-**Exemplo de useState inline organizado (melhor que hook órfão):**
-```typescript
-const MyComponent = () => {
-  // === STATE: Data ===
-  const { data, isLoading } = useMyData(id);
-
-  // === STATE: UI ===
-  const [selectedId, setSelectedId] = useState<string | null>(null);
-  const [isSheetOpen, setIsSheetOpen] = useState(false);
-
-  // === STATE: Filters ===
-  const [search, setSearch] = useState('');
-  const filteredData = useMemo(() => data?.filter(...), [data, search]);
-
-  // ... resto
-};
-```
-
-### GATE 2: Validação Final (OBRIGATÓRIO)
-
-```bash
-# Após terminar, verificar linhas TOTAIS
-find {pasta-criada} -name "*.ts" -o -name "*.tsx" | xargs wc -l | tail -1
-
-# Se linhas_depois > linhas_antes → FALHA, simplificar ou reverter
-```
-
-| Métrica | Limite | Se Falhar |
-|---------|--------|-----------|
-| Linhas totais | ≤ original | Simplificar |
-| Arquivos | ≤7 por feature | Consolidar |
-| Hooks órfãos | 0 | Mover inline |
-
----
-
-## Required Rules (MUST)
-
-### 1. Line Limits
-
-| Type | Max | Ideal |
-|------|--------|-------|
-| Template (orchestrator) | **100** | 50-80 |
-| Organism | 200 | 100-150 |
-| Molecule | 100 | 50-80 |
-| Hook | 150 | 80-120 |
-| types.ts | No limit | - |
-| data/*.ts | No limit | - |
-
-**Validation:**
-```bash
-# Check largest file (except types.ts and data/)
-find . -name "*.tsx" -o -name "*.ts" | grep -v types.ts | grep -v /data/ | xargs wc -l | sort -rn | head -5
-```
-
-### 2. Folder Structure
-
-```
-{domain}/{feature}/
-├── types.ts           # REQUIRED
-├── index.ts           # REQUIRED
-├── {Feature}Template.tsx  # REQUIRED (orchestrator)
-├── hooks/
-│   └── index.ts       # REQUIRED if has hooks
-├── molecules/
-│   └── index.ts       # REQUIRED if has molecules
-└── organisms/
-    └── index.ts       # REQUIRED
-```
-
-### 3. Naming Conventions
-
-| Type | Pattern | Example |
-|------|---------|---------|
-| Template | `{Feature}Template.tsx` | `CoursesTemplate.tsx` |
-| Organism | `{Feature}{Type}.tsx` | `CoursesListView.tsx` |
-| Molecule | `{Name}.tsx` | `StatCard.tsx` |
-| Hook (data) | `use{Feature}Data.ts` | `useCoursesData.ts` |
-| Hook (filters) | `use{Feature}Filters.ts` | `useCoursesFilters.ts` |
-| Hook (dialog) | `use{Name}Dialog.ts` | `useCreateDialog.ts` |
-| Types | `types.ts` | `types.ts` |
-| Index | `index.ts` | `index.ts` |
-
-### 4. Required Extraction
-
-**ALWAYS extract:**
-- [ ] `render{X}()` → `{X}View.tsx` or `{X}Section.tsx`
-- [ ] `useState` grouped by concern → custom hook
-- [ ] Color/icon configs → `types.ts`
-- [ ] Mock/static data → `data/`
-
-### 5. TypeScript
-
-- [ ] `npx tsc --noEmit` must pass with 0 errors
-- [ ] No `any` types (except when unavoidable)
-- [ ] Props typed with interfaces in `types.ts`
-- [ ] Hooks with explicit or inferred return type
-
-### 6. Types Consistency
-
-**RULE:** Every type imported in `data/*.ts` MUST exist in `types.ts`
-
-```typescript
-// ❌ WRONG - import type that doesn't exist
-// data/my-data.ts
-import type { FaqItem, CourseModule } from '../types';
-// but types.ts doesn't have FaqItem or CourseModule → ERROR!
-
-// ✅ CORRECT - types.ts has all interfaces
-// types.ts
-export interface FaqItem { ... }
-export interface CourseModule { ... }
-
-// data/my-data.ts
-import type { FaqItem, CourseModule } from '../types'; // OK!
-```
-
-**Validation:**
-```bash
-# Check imported vs exported types
-grep -h "from '../types'" {folder}/data/*.ts
-grep "export interface\|export type" {folder}/types.ts
-```
-
-### 7. AppRoutes.tsx Updates
-
-**RULE:** If moving a Template to a new folder, MUST update `AppRoutes.tsx`
-
-```typescript
-// If moving: books/templates/BookDetailTemplate.tsx
-//        to: books/book-detail/BookDetailTemplate.tsx
-
-// BEFORE in AppRoutes.tsx:
-const BookDetailTemplate = React.lazy(() => import('./books/templates/BookDetailTemplate'));
-
-// AFTER in AppRoutes.tsx:
-const BookDetailTemplate = React.lazy(() => import('./books/book-detail/BookDetailTemplate'));
-```
-
-**Validation:**
-```bash
-# Check if import exists in new path
-grep "BookDetailTemplate" app/components/AppRoutes.tsx
-npm run typecheck | grep "Cannot find module"
-```
-
-### 8. Find ALL Importers
-
-**RULE:** BEFORE moving any file, find ALL files that import it.
-
-```bash
-# Required before moving
-grep -rn "{ComponentName}" app/components/ --include="*.tsx" --include="*.ts" | grep "import"
-```
-
-**Common error example:**
-```
-# Component: CreatePersona
-# Subagent moved to: create-persona/CreatePersona.tsx
-# Subagent updated: views/index.ts (re-export)
-# Subagent FORGOT: PersonasTemplate.tsx (direct import)
-# RESULT: broken import!
-```
-
-**Import checklist:**
-- [ ] views/index.ts (re-export)
-- [ ] {Parent}Template.tsx (direct import)
-- [ ] AppRoutes.tsx (lazy import)
-- [ ] Other components that use it
-
-### 9. Preserve Hook Types
-
-**RULE:** Check EXACT types of hooks BEFORE creating types.ts
-
-```typescript
-// ❌ WRONG - Create type without checking hook
-// types.ts
-interface Props {
-  slug?: string;  // useParams returns string | undefined
-}
-// hook/useData.ts
-const { data } = useCourseContents(slug); // useCourseContents expects string | null
-// RESULT: Type error!
-
-// ✅ CORRECT - Check hook first
-// 1. Open hook and see: useCourseContents(slug: string | null)
-// 2. In component, convert: useCourseContents(slug ?? null)
-```
-
-**Validation BEFORE creating types.ts:**
-```bash
-# See hook signature
-grep -A5 "export function use" app/hooks/useYYY.ts
-grep -A5 "export const use" app/hooks/useYYY.ts
-```
-
-### 10. Real TypeScript Validation
-
-**RULE:** Run REAL tsc and verify output, don't lie.
-
-### 11. Type Definition Order
-
-**RULE:** Define types BEFORE using them in interfaces.
-
-```typescript
-// ❌ WRONG - type used before defined
-export interface Props {
-  onNavigate: (view: CourseView) => void;  // CourseView not defined yet!
-}
-export type CourseView = 'overview' | 'research';  // Too late
-
-// ✅ CORRECT - type defined first
-export type CourseView = 'overview' | 'research';
-export interface Props {
-  onNavigate: (view: CourseView) => void;  // OK
-}
-```
-
-### 12. Nullable Consistency
-
-**RULE:** Match exact nullability between source and consumer.
-
-```typescript
-// useParams returns: string | undefined
-// useCourseContents expects: string | null
-
-// ❌ WRONG - passing undefined to null parameter
-const { slug } = useParams();
-useCourseContents(slug);  // Type error!
-
-// ✅ CORRECT - convert undefined to null
-const { slug } = useParams();
-useCourseContents(slug ?? null);
-```
-
-**Common conversions:**
-| Source | Target | Fix |
-|--------|--------|-----|
-| `undefined` | `null` | `value ?? null` |
-| `null` | `undefined` | `value ?? undefined` |
-| `string \| undefined` | `string \| null` | `value ?? null` |
-
-### 13. String to Union Type Casting
-
-**RULE:** When data comes from objects with string keys, cast to union type.
-
-```typescript
-// Pipeline step has key as string
-const pipeline = [{ key: 'overview', ... }, { key: 'research', ... }];
-
-// But onNavigate expects union type
-onNavigate: (view: 'overview' | 'research') => void;
-
-// ❌ WRONG - string not assignable to union
-onClick={() => onNavigate(step.key)}  // Type error!
-
-// ✅ CORRECT - cast to expected type
-onClick={() => onNavigate(step.key as CourseView)}
-```
-
-### 14. Props Consistency Across Components
-
-**RULE:** When parent and child share a callback, use SAME type.
-
-```typescript
-// ❌ WRONG - different types for same callback
-// Parent:
-onNavigate: (view: 'overview' | 'research') => void;
-// Child:
-onNavigate: (view: string) => void;  // Incompatible!
-
-// ✅ CORRECT - shared type
-export type CourseView = 'overview' | 'research';
-
-// Parent:
-onNavigate: (view: CourseView) => void;
-// Child:
-onNavigate: (view: CourseView) => void;  // Same type
-```
-
-```bash
-# Required after refactoring
-npx tsc --noEmit 2>&1 | grep -E "(error|{ComponentName})" | head -30
-
-# If returns ANYTHING → FIX BEFORE RETURNING
-# DO NOT report "0 errors" without running this command
-```
-
-**Common errors tsc detects:**
-| Error | Cause | Fix |
-|-------|-------|-----|
-| `Cannot find module` | Wrong import path | Update import |
-| `Type 'undefined' not assignable to 'null'` | Hook expects null | `value ?? null` |
-| `Type 'string' not assignable to union` | Generic type | Use exact union type |
-| `Property does not exist` | Incompatible type | Check original type |
-
----
-
-## Recommended Rules (SHOULD)
-
-### 1. Template Orchestrator
-
-The template should be ONLY composition:
-
-```typescript
-// ✅ GOOD - composition only
-export const FeatureTemplate = () => {
-  const data = useFeatureData();
-  const filters = useFeatureFilters(data.items);
-
-  return (
-    <div>
-      <FeatureHeader onRefresh={data.refetch} />
-      <FeatureListView items={filters.filteredItems} />
-    </div>
-  );
-};
-
-// ❌ BAD - logic in template
-export const FeatureTemplate = () => {
-  const [items, setItems] = useState([]);
-
-  useEffect(() => {
-    fetch('/api/items').then(r => r.json()).then(setItems);
-  }, []);
-
-  const filteredItems = items.filter(i => i.active);
-
-  return (
-    <div>
-      {filteredItems.map(item => (
-        <div key={item.id}>{item.name}</div>
-      ))}
-    </div>
-  );
-};
-```
-
-### 2. Hooks
-
-- Um hook = um concern
-- Hooks podem usar outros hooks
-- Hooks NÃO devem renderizar JSX
-- Retornar objeto com estado + actions
-
-```typescript
-// ✅ BOM
-export function useFilters(items) {
-  const [search, setSearch] = useState('');
-  const filtered = useMemo(() =>
-    items.filter(i => i.name.includes(search)),
-    [items, search]
-  );
-  return { search, setSearch, filtered };
-}
-
-// ❌ RUIM - mistura concerns
-export function useEverything() {
-  const [items, setItems] = useState([]);
-  const [search, setSearch] = useState('');
-  const [isOpen, setIsOpen] = useState(false);
-  // ... 20 estados diferentes
-}
-```
-
-### 3. Organisms
-
-- Recebe props, não busca dados
-- Pode ter estado de UI local (hover, expanded)
-- Não deve chamar APIs diretamente
-- Composição de molecules
-
-```typescript
-// ✅ BOM - recebe props
-export const ListView = ({ items, onItemClick }: Props) => {
-  return items.map(item => (
-    <ItemCard key={item.id} item={item} onClick={() => onItemClick(item)} />
-  ));
-};
-
-// ❌ RUIM - busca dados internamente
-export const ListView = () => {
-  const [items, setItems] = useState([]);
-  useEffect(() => { fetchItems().then(setItems); }, []);
-  return items.map(item => <div>{item.name}</div>);
-};
-```
-
-### 4. Molecules
-
-- Stateless (ou estado de UI mínimo)
-- Reutilizáveis em múltiplos contextos
-- Props simples e bem definidas
-- Sem dependências de contexto específico
-
-### 5. Shared Components
-
-Antes de criar um molecule/hook:
-1. Verificar se existe em `shared/molecules/`
-2. Verificar se existe em `shared/hooks/`
-3. Se for genérico (usado em 3+ lugares) → criar em shared/
-4. Se for específico do domínio → criar local
-
----
-
-## Anti-Patterns (NEVER)
-
-### 1. Imports Circulares
-
-```typescript
-// ❌ NUNCA - hooks importando organisms
-// hooks/useData.ts
-import { ListView } from '../organisms/ListView'; // ERRADO!
-
-// ❌ NUNCA - molecules importando organisms
-// molecules/Card.ts
-import { Header } from '../organisms/Header'; // ERRADO!
-```
-
-**Hierarquia correta:**
-```
-types.ts ← hooks ← molecules ← organisms ← Template
-```
-
-### 2. Props Drilling Excessivo
-
-```typescript
-// ❌ RUIM - passar 10+ props
-<ListView
-  items={items}
-  loading={loading}
-  error={error}
-  onRefresh={refetch}
-  search={search}
-  setSearch={setSearch}
-  filter={filter}
-  setFilter={setFilter}
-  sortBy={sortBy}
-  setSortBy={setSortBy}
-  // ...
-/>
-
-// ✅ MELHOR - agrupar em objetos
-<ListView
-  data={{ items, loading, error }}
-  filters={filtersState}
-  actions={{ onRefresh, onItemClick }}
-/>
-```
-
-### 3. Arquivos Gigantes
-
-```typescript
-// ❌ NUNCA - organism com 500 linhas
-// Sinal que precisa ser dividido em múltiplos organisms
-
-// ❌ NUNCA - hook com 300 linhas
-// Sinal que precisa ser dividido em múltiplos hooks
-```
-
-### 4. Lógica no Render
-
-```typescript
-// ❌ RUIM
-return (
-  <div>
-    {items.filter(i => i.active).sort((a,b) => a.name.localeCompare(b.name)).map(...)}
-  </div>
-);
-
-// ✅ BOM - processar antes
-const sortedItems = useMemo(() =>
-  items.filter(i => i.active).sort((a,b) => a.name.localeCompare(b.name)),
-  [items]
-);
-return <div>{sortedItems.map(...)}</div>;
-```
-
----
-
-## Métricas de Sucesso
-
-### Redução Esperada
-
-| Tier | Antes | Depois | Redução |
-|------|-------|--------|---------|
-| TIER 1 (>800) | 800-2000 | 50-200 | 85-95% |
-| TIER 2 (500-800) | 500-800 | 40-150 | 80-90% |
-| TIER 3 (300-500) | 300-500 | 30-100 | 70-80% |
-
-### Número de Arquivos
-
-| Componente Original | Arquivos Esperados |
-|---------------------|-------------------|
-| 300-500 linhas | 8-12 arquivos |
-| 500-800 linhas | 12-18 arquivos |
-| 800-1500 linhas | 15-25 arquivos |
-| 1500+ linhas | 20-35 arquivos |
-
-### Qualidade
-
-- [ ] 0 erros TypeScript
-- [ ] 0 imports circulares
-- [ ] 0 arquivos >200 linhas (exceto types/data)
-- [ ] 100% funcionalidade preservada
-- [ ] Barrel exports funcionando
-
----
-
-## Final Validation Checklist
-
-```markdown
-## Refactoring Validation: {ComponentName}
-
-### Structure
-- [ ] Folder created at `{domain}/{feature}/`
-- [ ] types.ts exists
-- [ ] index.ts with barrel exports
-- [ ] hooks/index.ts exists
-- [ ] organisms/index.ts exists
-
-### Code
-- [ ] Template ≤200 lines
-- [ ] No file >200 lines (except types/data)
-- [ ] All render{X} extracted
-- [ ] All useState grouped in hooks
-- [ ] npx tsc --noEmit passes
-
-### Functionality
-- [ ] Renders same as original
-- [ ] Interactions work
-- [ ] Edge cases handled (loading, empty, error)
-
-### Metrics
-- Before: _____ lines
-- After: _____ lines (orchestrator)
-- Reduction: _____%
-- Files created: _____
-```
-
----
-
-*Rules v1.3 - 2026-01-05*
-*Added rules 8-14 based on Wave 1.1 subagent errors:*
-*- Rule 8: Find ALL importers before moving*
-*- Rule 9: Preserve hook types (undefined vs null)*
-*- Rule 10: Real TypeScript validation*
-*- Rule 11: Type definition order (define before use)*
-*- Rule 12: Nullable consistency (undefined vs null)*
-*- Rule 13: String to union type casting*
-*- Rule 14: Props consistency across components*
-*Based on 18+ refactorings + Wave 1.1 error analysis*
+# Atomic Design Refactoring Rules
+
+> Validation rules and best practices for Atomic Design refactoring.
+> Based on 18+ refactored components with 91% average reduction.
+>
+> **v2.0 - Jan/2026:** Adicionados gates anti-over-engineering após análise mostrar +111% código em alguns casos.
+
+---
+
+## ⛔ GATES ANTI-OVER-ENGINEERING (LER PRIMEIRO!)
+
+> **LIÇÃO JAN/2026:** Atomizamos 22 componentes. Em alguns casos, FragmentsTab foi de 475 → 1003 linhas (+111%) com 73% dos hooks sem reuso externo.
+
+### GATE 0: Devo Atomizar?
+
+| Linhas | useState | Decisão |
+|--------|----------|---------|
+| >800 | qualquer | **SIM** - atomizar |
+| 500-800 | >7 | **SIM** - atomizar |
+| 500-800 | ≤7 | **TALVEZ** - só se hooks serão reusados |
+| <500 | qualquer | **NÃO** - organizar inline |
+
+### GATE 1: Antes de Criar Cada Hook
+
+```
+PERGUNTA OBRIGATÓRIA: Esse hook será usado em OUTRO componente?
+
+SE SIM → criar o hook (listar onde será usado)
+SE NÃO → NÃO criar, manter useState inline com comentários organizados
+```
+
+**Exemplo de useState inline organizado (melhor que hook órfão):**
+```typescript
+const MyComponent = () => {
+  // === STATE: Data ===
+  const { data, isLoading } = useMyData(id);
+
+  // === STATE: UI ===
+  const [selectedId, setSelectedId] = useState<string | null>(null);
+  const [isSheetOpen, setIsSheetOpen] = useState(false);
+
+  // === STATE: Filters ===
+  const [search, setSearch] = useState('');
+  const filteredData = useMemo(() => data?.filter(...), [data, search]);
+
+  // ... resto
+};
+```
+
+### GATE 2: Validação Final (OBRIGATÓRIO)
+
+```bash
+# Após terminar, verificar linhas TOTAIS
+find {pasta-criada} -name "*.ts" -o -name "*.tsx" | xargs wc -l | tail -1
+
+# Se linhas_depois > linhas_antes → FALHA, simplificar ou reverter
+```
+
+| Métrica | Limite | Se Falhar |
+|---------|--------|-----------|
+| Linhas totais | ≤ original | Simplificar |
+| Arquivos | ≤7 por feature | Consolidar |
+| Hooks órfãos | 0 | Mover inline |
+
+---
+
+## Required Rules (MUST)
+
+### 1. Line Limits
+
+| Type | Max | Ideal |
+|------|--------|-------|
+| Template (orchestrator) | **100** | 50-80 |
+| Organism | 200 | 100-150 |
+| Molecule | 100 | 50-80 |
+| Hook | 150 | 80-120 |
+| types.ts | No limit | - |
+| data/*.ts | No limit | - |
+
+**Validation:**
+```bash
+# Check largest file (except types.ts and data/)
+find . -name "*.tsx" -o -name "*.ts" | grep -v types.ts | grep -v /data/ | xargs wc -l | sort -rn | head -5
+```
+
+### 2. Folder Structure
+
+```
+{domain}/{feature}/
+├── types.ts           # REQUIRED
+├── index.ts           # REQUIRED
+├── {Feature}Template.tsx  # REQUIRED (orchestrator)
+├── hooks/
+│   └── index.ts       # REQUIRED if has hooks
+├── molecules/
+│   └── index.ts       # REQUIRED if has molecules
+└── organisms/
+    └── index.ts       # REQUIRED
+```
+
+### 3. Naming Conventions
+
+| Type | Pattern | Example |
+|------|---------|---------|
+| Template | `{Feature}Template.tsx` | `CoursesTemplate.tsx` |
+| Organism | `{Feature}{Type}.tsx` | `CoursesListView.tsx` |
+| Molecule | `{Name}.tsx` | `StatCard.tsx` |
+| Hook (data) | `use{Feature}Data.ts` | `useCoursesData.ts` |
+| Hook (filters) | `use{Feature}Filters.ts` | `useCoursesFilters.ts` |
+| Hook (dialog) | `use{Name}Dialog.ts` | `useCreateDialog.ts` |
+| Types | `types.ts` | `types.ts` |
+| Index | `index.ts` | `index.ts` |
+
+### 4. Required Extraction
+
+**ALWAYS extract:**
+- [ ] `render{X}()` → `{X}View.tsx` or `{X}Section.tsx`
+- [ ] `useState` grouped by concern → custom hook
+- [ ] Color/icon configs → `types.ts`
+- [ ] Mock/static data → `data/`
+
+### 5. TypeScript
+
+- [ ] `npx tsc --noEmit` must pass with 0 errors
+- [ ] No `any` types (except when unavoidable)
+- [ ] Props typed with interfaces in `types.ts`
+- [ ] Hooks with explicit or inferred return type
+
+### 6. Types Consistency
+
+**RULE:** Every type imported in `data/*.ts` MUST exist in `types.ts`
+
+```typescript
+// ❌ WRONG - import type that doesn't exist
+// data/my-data.ts
+import type { FaqItem, CourseModule } from '../types';
+// but types.ts doesn't have FaqItem or CourseModule → ERROR!
+
+// ✅ CORRECT - types.ts has all interfaces
+// types.ts
+export interface FaqItem { ... }
+export interface CourseModule { ... }
+
+// data/my-data.ts
+import type { FaqItem, CourseModule } from '../types'; // OK!
+```
+
+**Validation:**
+```bash
+# Check imported vs exported types
+grep -h "from '../types'" {folder}/data/*.ts
+grep "export interface\|export type" {folder}/types.ts
+```
+
+### 7. AppRoutes.tsx Updates
+
+**RULE:** If moving a Template to a new folder, MUST update `AppRoutes.tsx`
+
+```typescript
+// If moving: books/templates/BookDetailTemplate.tsx
+//        to: books/book-detail/BookDetailTemplate.tsx
+
+// BEFORE in AppRoutes.tsx:
+const BookDetailTemplate = React.lazy(() => import('./books/templates/BookDetailTemplate'));
+
+// AFTER in AppRoutes.tsx:
+const BookDetailTemplate = React.lazy(() => import('./books/book-detail/BookDetailTemplate'));
+```
+
+**Validation:**
+```bash
+# Check if import exists in new path
+grep "BookDetailTemplate" app/components/AppRoutes.tsx
+npm run typecheck | grep "Cannot find module"
+```
+
+### 8. Find ALL Importers
+
+**RULE:** BEFORE moving any file, find ALL files that import it.
+
+```bash
+# Required before moving
+grep -rn "{ComponentName}" app/components/ --include="*.tsx" --include="*.ts" | grep "import"
+```
+
+**Common error example:**
+```
+# Component: CreatePersona
+# Subagent moved to: create-persona/CreatePersona.tsx
+# Subagent updated: views/index.ts (re-export)
+# Subagent FORGOT: PersonasTemplate.tsx (direct import)
+# RESULT: broken import!
+```
+
+**Import checklist:**
+- [ ] views/index.ts (re-export)
+- [ ] {Parent}Template.tsx (direct import)
+- [ ] AppRoutes.tsx (lazy import)
+- [ ] Other components that use it
+
+### 9. Preserve Hook Types
+
+**RULE:** Check EXACT types of hooks BEFORE creating types.ts
+
+```typescript
+// ❌ WRONG - Create type without checking hook
+// types.ts
+interface Props {
+  slug?: string;  // useParams returns string | undefined
+}
+// hook/useData.ts
+const { data } = useCourseContents(slug); // useCourseContents expects string | null
+// RESULT: Type error!
+
+// ✅ CORRECT - Check hook first
+// 1. Open hook and see: useCourseContents(slug: string | null)
+// 2. In component, convert: useCourseContents(slug ?? null)
+```
+
+**Validation BEFORE creating types.ts:**
+```bash
+# See hook signature
+grep -A5 "export function use" app/hooks/useYYY.ts
+grep -A5 "export const use" app/hooks/useYYY.ts
+```
+
+### 10. Real TypeScript Validation
+
+**RULE:** Run REAL tsc and verify output, don't lie.
+
+### 11. Type Definition Order
+
+**RULE:** Define types BEFORE using them in interfaces.
+
+```typescript
+// ❌ WRONG - type used before defined
+export interface Props {
+  onNavigate: (view: CourseView) => void;  // CourseView not defined yet!
+}
+export type CourseView = 'overview' | 'research';  // Too late
+
+// ✅ CORRECT - type defined first
+export type CourseView = 'overview' | 'research';
+export interface Props {
+  onNavigate: (view: CourseView) => void;  // OK
+}
+```
+
+### 12. Nullable Consistency
+
+**RULE:** Match exact nullability between source and consumer.
+
+```typescript
+// useParams returns: string | undefined
+// useCourseContents expects: string | null
+
+// ❌ WRONG - passing undefined to null parameter
+const { slug } = useParams();
+useCourseContents(slug);  // Type error!
+
+// ✅ CORRECT - convert undefined to null
+const { slug } = useParams();
+useCourseContents(slug ?? null);
+```
+
+**Common conversions:**
+| Source | Target | Fix |
+|--------|--------|-----|
+| `undefined` | `null` | `value ?? null` |
+| `null` | `undefined` | `value ?? undefined` |
+| `string \| undefined` | `string \| null` | `value ?? null` |
+
+### 13. String to Union Type Casting
+
+**RULE:** When data comes from objects with string keys, cast to union type.
+
+```typescript
+// Pipeline step has key as string
+const pipeline = [{ key: 'overview', ... }, { key: 'research', ... }];
+
+// But onNavigate expects union type
+onNavigate: (view: 'overview' | 'research') => void;
+
+// ❌ WRONG - string not assignable to union
+onClick={() => onNavigate(step.key)}  // Type error!
+
+// ✅ CORRECT - cast to expected type
+onClick={() => onNavigate(step.key as CourseView)}
+```
+
+### 14. Props Consistency Across Components
+
+**RULE:** When parent and child share a callback, use SAME type.
+
+```typescript
+// ❌ WRONG - different types for same callback
+// Parent:
+onNavigate: (view: 'overview' | 'research') => void;
+// Child:
+onNavigate: (view: string) => void;  // Incompatible!
+
+// ✅ CORRECT - shared type
+export type CourseView = 'overview' | 'research';
+
+// Parent:
+onNavigate: (view: CourseView) => void;
+// Child:
+onNavigate: (view: CourseView) => void;  // Same type
+```
+
+```bash
+# Required after refactoring
+npx tsc --noEmit 2>&1 | grep -E "(error|{ComponentName})" | head -30
+
+# If returns ANYTHING → FIX BEFORE RETURNING
+# DO NOT report "0 errors" without running this command
+```
+
+**Common errors tsc detects:**
+| Error | Cause | Fix |
+|-------|-------|-----|
+| `Cannot find module` | Wrong import path | Update import |
+| `Type 'undefined' not assignable to 'null'` | Hook expects null | `value ?? null` |
+| `Type 'string' not assignable to union` | Generic type | Use exact union type |
+| `Property does not exist` | Incompatible type | Check original type |
+
+---
+
+## Recommended Rules (SHOULD)
+
+### 1. Template Orchestrator
+
+The template should be ONLY composition:
+
+```typescript
+// ✅ GOOD - composition only
+export const FeatureTemplate = () => {
+  const data = useFeatureData();
+  const filters = useFeatureFilters(data.items);
+
+  return (
+    <div>
+      <FeatureHeader onRefresh={data.refetch} />
+      <FeatureListView items={filters.filteredItems} />
+    </div>
+  );
+};
+
+// ❌ BAD - logic in template
+export const FeatureTemplate = () => {
+  const [items, setItems] = useState([]);
+
+  useEffect(() => {
+    fetch('/api/items').then(r => r.json()).then(setItems);
+  }, []);
+
+  const filteredItems = items.filter(i => i.active);
+
+  return (
+    <div>
+      {filteredItems.map(item => (
+        <div key={item.id}>{item.name}</div>
+      ))}
+    </div>
+  );
+};
+```
+
+### 2. Hooks
+
+- Um hook = um concern
+- Hooks podem usar outros hooks
+- Hooks NÃO devem renderizar JSX
+- Retornar objeto com estado + actions
+
+```typescript
+// ✅ BOM
+export function useFilters(items) {
+  const [search, setSearch] = useState('');
+  const filtered = useMemo(() =>
+    items.filter(i => i.name.includes(search)),
+    [items, search]
+  );
+  return { search, setSearch, filtered };
+}
+
+// ❌ RUIM - mistura concerns
+export function useEverything() {
+  const [items, setItems] = useState([]);
+  const [search, setSearch] = useState('');
+  const [isOpen, setIsOpen] = useState(false);
+  // ... 20 estados diferentes
+}
+```
+
+### 3. Organisms
+
+- Recebe props, não busca dados
+- Pode ter estado de UI local (hover, expanded)
+- Não deve chamar APIs diretamente
+- Composição de molecules
+
+```typescript
+// ✅ BOM - recebe props
+export const ListView = ({ items, onItemClick }: Props) => {
+  return items.map(item => (
+    <ItemCard key={item.id} item={item} onClick={() => onItemClick(item)} />
+  ));
+};
+
+// ❌ RUIM - busca dados internamente
+export const ListView = () => {
+  const [items, setItems] = useState([]);
+  useEffect(() => { fetchItems().then(setItems); }, []);
+  return items.map(item => <div>{item.name}</div>);
+};
+```
+
+### 4. Molecules
+
+- Stateless (ou estado de UI mínimo)
+- Reutilizáveis em múltiplos contextos
+- Props simples e bem definidas
+- Sem dependências de contexto específico
+
+### 5. Shared Components
+
+Antes de criar um molecule/hook:
+1. Verificar se existe em `shared/molecules/`
+2. Verificar se existe em `shared/hooks/`
+3. Se for genérico (usado em 3+ lugares) → criar em shared/
+4. Se for específico do domínio → criar local
+
+---
+
+## Anti-Patterns (NEVER)
+
+### 1. Imports Circulares
+
+```typescript
+// ❌ NUNCA - hooks importando organisms
+// hooks/useData.ts
+import { ListView } from '../organisms/ListView'; // ERRADO!
+
+// ❌ NUNCA - molecules importando organisms
+// molecules/Card.ts
+import { Header } from '../organisms/Header'; // ERRADO!
+```
+
+**Hierarquia correta:**
+```
+types.ts ← hooks ← molecules ← organisms ← Template
+```
+
+### 2. Props Drilling Excessivo
+
+```typescript
+// ❌ RUIM - passar 10+ props
+<ListView
+  items={items}
+  loading={loading}
+  error={error}
+  onRefresh={refetch}
+  search={search}
+  setSearch={setSearch}
+  filter={filter}
+  setFilter={setFilter}
+  sortBy={sortBy}
+  setSortBy={setSortBy}
+  // ...
+/>
+
+// ✅ MELHOR - agrupar em objetos
+<ListView
+  data={{ items, loading, error }}
+  filters={filtersState}
+  actions={{ onRefresh, onItemClick }}
+/>
+```
+
+### 3. Arquivos Gigantes
+
+```typescript
+// ❌ NUNCA - organism com 500 linhas
+// Sinal que precisa ser dividido em múltiplos organisms
+
+// ❌ NUNCA - hook com 300 linhas
+// Sinal que precisa ser dividido em múltiplos hooks
+```
+
+### 4. Lógica no Render
+
+```typescript
+// ❌ RUIM
+return (
+  <div>
+    {items.filter(i => i.active).sort((a,b) => a.name.localeCompare(b.name)).map(...)}
+  </div>
+);
+
+// ✅ BOM - processar antes
+const sortedItems = useMemo(() =>
+  items.filter(i => i.active).sort((a,b) => a.name.localeCompare(b.name)),
+  [items]
+);
+return <div>{sortedItems.map(...)}</div>;
+```
+
+---
+
+## Métricas de Sucesso
+
+### Redução Esperada
+
+| Tier | Antes | Depois | Redução |
+|------|-------|--------|---------|
+| TIER 1 (>800) | 800-2000 | 50-200 | 85-95% |
+| TIER 2 (500-800) | 500-800 | 40-150 | 80-90% |
+| TIER 3 (300-500) | 300-500 | 30-100 | 70-80% |
+
+### Número de Arquivos
+
+| Componente Original | Arquivos Esperados |
+|---------------------|-------------------|
+| 300-500 linhas | 8-12 arquivos |
+| 500-800 linhas | 12-18 arquivos |
+| 800-1500 linhas | 15-25 arquivos |
+| 1500+ linhas | 20-35 arquivos |
+
+### Qualidade
+
+- [ ] 0 erros TypeScript
+- [ ] 0 imports circulares
+- [ ] 0 arquivos >200 linhas (exceto types/data)
+- [ ] 100% funcionalidade preservada
+- [ ] Barrel exports funcionando
+
+---
+
+## Final Validation Checklist
+
+```markdown
+## Refactoring Validation: {ComponentName}
+
+### Structure
+- [ ] Folder created at `{domain}/{feature}/`
+- [ ] types.ts exists
+- [ ] index.ts with barrel exports
+- [ ] hooks/index.ts exists
+- [ ] organisms/index.ts exists
+
+### Code
+- [ ] Template ≤200 lines
+- [ ] No file >200 lines (except types/data)
+- [ ] All render{X} extracted
+- [ ] All useState grouped in hooks
+- [ ] npx tsc --noEmit passes
+
+### Functionality
+- [ ] Renders same as original
+- [ ] Interactions work
+- [ ] Edge cases handled (loading, empty, error)
+
+### Metrics
+- Before: _____ lines
+- After: _____ lines (orchestrator)
+- Reduction: _____%
+- Files created: _____
+```
+
+---
+
+*Rules v1.3 - 2026-01-05*
+*Added rules 8-14 based on Wave 1.1 subagent errors:*
+*- Rule 8: Find ALL importers before moving*
+*- Rule 9: Preserve hook types (undefined vs null)*
+*- Rule 10: Real TypeScript validation*
+*- Rule 11: Type definition order (define before use)*
+*- Rule 12: Nullable consistency (undefined vs null)*
+*- Rule 13: String to union type casting*
+*- Rule 14: Props consistency across components*
+*Based on 18+ refactorings + Wave 1.1 error analysis*