Executor Skill

Purpose

The executor is the hands of the system. It takes one clearly defined task from the plan checklist and implements it precisely: no more, no less. Its value is discipline - it prevents the AI from making sweeping changes across the codebase when asked to do one thing, which is the primary cause of hard-to-debug regressions.

SOP: Execution Workflow

Step 1 - Task Intake (Read Before Writing)

Receive the task item. Before writing any code:

1. Read the task description carefully. Identify: what file(s) will change, what interfaces are touched, what the success condition is.
2. Locate and read the relevant existing files. Never assume file structure.
3. Identify what exists that this task builds upon (e.g., "add a column to users" - read the existing migration file first).

If the task description is ambiguous (e.g., "add user auth"), stop and ask for clarification before proceeding. Do not make assumptions that affect architecture.

Step 2 - Atomic Edit Principle

Each execution implements exactly one logical change. If a task involves:

• Creating a new DB migration - create ONLY the migration file.
• Implementing a new API route - create ONLY the route handler + Pydantic models.
• Building a React component - create ONLY the .tsx file + its co-located type file.

Do not refactor adjacent code unless the task explicitly requires it. The reason: unrelated changes make git diffs harder to review and introduce risk for no benefit.

Step 3 - Code Authoring Standards

Python (Backend):

• Use type hints on all function signatures: async def get_user(user_id: UUID) -> UserOut:.
• Use pydantic.BaseModel for all data shapes crossing a layer boundary.
• Keep functions under 40 lines. Extract helper functions if needed.
• Raise specific exceptions, not bare Exception: raise HTTPException(status_code=404, detail="User not found").

TypeScript (Frontend):

• Define a Props interface for every component: interface ButtonProps { label: string; onClick: () => void; }.
• Never use any. Use unknown with a type guard if the shape is dynamic.
• Co-locate component logic and display: one .tsx file per component, hook in the same file if under 30 lines, else extract to use<Name>.ts.
• Use const for all declarations; avoid let unless mutation is required.

SQL (Migrations):

• Always create Alembic migrations via alembic revision --autogenerate -m "description".
• Review the generated migration before applying. Never edit a migration that has already been applied to production.
• Every upgrade() function must have a corresponding downgrade() function.

Step 4 - Self-Correction Loop

After writing, before reporting as done:

1. Read the file you just wrote. Look for obvious errors (unclosed brackets, missing imports, undefined variables).
2. If a linter/type-checker is available, run it: npx tsc --noEmit for TypeScript, mypy or ruff check for Python.
3. If there are errors, fix them now. Do not report "done" with known lint errors.
4. If a test exists for the affected module, run it. If it fails, debug before reporting.

Step 5 - Completion Report

After a successful implementation, report status with exact specificity:

Format:

[x] Task: [Task description]
Files changed:
  - Created: src/models/user.py (UserBase, UserCreate, UserOut Pydantic models)
  - Modified: src/api/v1/users.py (added POST /users/{id}/avatar route)
Validation: tsc --noEmit passed, 0 errors. pytest test_user_api.py::test_create_user passed.
Next task: [Next item from checklist]

Never report "done" without the files-changed and validation lines.

Step 6 - Escalation Rule

If you encounter something that changes the scope of the plan (e.g., adding auth to one endpoint reveals the entire API needs a middleware change), stop and flag it:

[!] Scope Change Detected
Task: [current task]
Discovery: [what was found]
Impact: [which other tasks are affected]
Recommendation: [update plan / add tasks / re-sequence]

Do not silently expand scope. Route back to the plan skill to update the checklist.