Goals

Goals

Use this skill to run a lightweight /goals workflow inside a Codex thread. Treat goals as the shared source of truth for what the user wants accomplished, what is in progress, and what remains.

When the work involves writing, reviewing, or refactoring code, combine this skill with $karpathy-guidelines: keep changes simple and surgical, surface assumptions, and make each goal verifiable.

This skill also incorporates goal-shaping practices from Matt Pocock's engineering skills collection: https://github.com/mattpocock/skills.git

Core Behavior

When the user asks for goals or uses /goals:

1. Show the current goal list if one exists in the thread.
2. If no goal list exists, create one from the current user request and visible context.
3. Keep goals concise, action-oriented, and testable.
4. Use statuses: pending, in_progress, completed, and blocked.
5. Keep at most one goal in_progress unless the work is explicitly parallel.
6. Update goals whenever the scope changes, a milestone is completed, or a blocker appears.
7. Do not turn tiny one-step tasks into ceremony. A single sentence is enough when the task is simple.

Prefer the built-in update_plan tool when available and the work has multiple steps. Otherwise, present a compact Markdown checklist.

Karpathy Mix-In

For coding tasks, shape goals around verifiable success criteria:

• Convert vague asks into observable outcomes.
• Prefer the smallest change that satisfies the user request.
• Add no speculative flexibility, abstractions, or adjacent cleanup goals.
• Include assumptions only when they affect implementation choices.
• Tie each implementation goal to a check: test, type check, lint, manual reproduction, screenshot, or inspected behavior.
• Every changed line should trace back to a goal or its verification.

Example:

**Goals**
- [~] in_progress: Reproduce the export failure -> verify with the failing flow or test
- [ ] pending: Patch the export path with the smallest scoped change -> verify with focused test
- [ ] pending: Confirm CSV export still works -> verify with existing or manual CSV check

Matt Pocock Mix-In

For non-trivial engineering work, shape goals around alignment, shared language, vertical slices, and feedback loops.

Alignment First

• If the request branches into multiple plausible designs, run a short grilling pass before locking goals.
• Ask one decisive question at a time and include your recommended answer.
• If the answer can be discovered from the codebase, inspect the code instead of asking.
• Turn the resolved answer into a goal or an assumption only when it changes the work.

Shared Language

• Prefer terms already defined in project docs such as CONTEXT.md, CONTEXT-MAP.md, and docs/adr/.
• If the user's wording conflicts with the project's glossary or code, call that out before finalizing goals.
• For persistent project goals, use the project's domain language so future agents and humans can search and act on the list.
• Add documentation goals only when the user asked for persistent artifacts or when a clarified term/decision must be captured.

Vertical Slices

• Break larger work into tracer-bullet goals: thin end-to-end slices that are independently demoable or verifiable.
• Prefer goals that cross the necessary layers for one behavior over horizontal goals like "update schema", "update API", and "update UI" as separate isolated tracks.
• Mark user-dependent decisions as blocked or explicitly HITL in the wording; keep agent-runnable work concrete and AFK-friendly.

Feedback Loops

• Treat the feedback loop as part of the goal, not an afterthought.
• For features, prefer behavior-first tests through public interfaces and a red-green-refactor rhythm when TDD is appropriate.
• For bugs, goals should usually follow: build/reuse a repro loop, reproduce, minimize, hypothesize, instrument, fix, regression-test, clean up.
• If no reliable verification loop exists, make creating one the active goal before changing production code.

Architecture Awareness

• When the relevant area is unfamiliar, include a goal to zoom out: map the modules, callers, and existing decisions before editing.
• Prefer goals that deepen or preserve useful modules: small interfaces, behavior behind the interface, and tests at the interface.
• Do not turn architecture curiosity into scope creep; only add refactor goals when they are required for the user's outcome or explicitly requested.

Handoff

• If work pauses or must move to another session, summarize active, completed, blocked, assumptions, and the next verification step.
• Do not duplicate content already captured in persistent docs, issues, PRDs, ADRs, commits, or diffs; reference those artifacts instead.

Goal Format

Use this shape for user-visible goal lists:

**Goals**
- [ ] pending: Inspect the current implementation
- [~] in_progress: Implement the requested behavior
- [x] completed: Run focused verification
- [!] blocked: Waiting on missing credentials

Use these check markers consistently:

• [ ] for pending
• [~] for in_progress
• [x] for completed
• [!] for blocked

When using update_plan, map the same items to tool statuses and keep the wording almost identical.

Creating Goals

When creating goals from a request:

1. Extract the user's intended outcome, not just the literal wording.
2. Include investigation only when it is necessary to make a safe change.
3. Include implementation goals for each meaningful work phase.
4. Include verification when behavior, code, or generated assets are changed.
5. Avoid generic goals like "understand the request" or "provide final answer".

Example:

User: "Fix the dashboard export bug and make sure CSV still works."

Good goals:

• Inspect export flow and reproduce the failure
• Fix dashboard export behavior
• Verify dashboard export and CSV export paths

Poor goals:

• Understand the bug
• Modify files
• Tell the user what changed

Updating Goals

Update goals as work progresses:

• Mark a goal in_progress before actively working on it.
• Mark it completed only after the relevant work is actually done.
• Add a goal if new required work appears.
• Split a goal if it becomes too broad to track.
• Mark a goal blocked with a short reason when progress depends on missing input, credentials, unavailable services, or an external failure.
• Remove or rewrite goals only when the user's intent changes or the existing wording is misleading.

When the user says things like "mark that done", "drop that", "add X", or "what is left", apply the update directly and show the revised list.

During Coding Work

For code changes:

1. Start with a short goal list when the task has more than one meaningful step.
2. Keep the active goal aligned with the next concrete action.
3. Mention goal progress in brief commentary updates during long tasks.
4. After edits, make verification explicit: tests, linting, type checks, manual browser checks, or a clear note that verification could not be run.
5. In the final response, summarize completed goals and any remaining blocked or deferred items.

Do not let the goal list replace engineering judgment. Still read the codebase, protect user changes, follow existing project patterns, and avoid touching unrelated code.

Persistence

By default, goals live in the current conversation context. If the user asks for persistent project goals, write or update a repository file such as GOALS.md, .codex/goals.md, or the path they name. Before creating a new persistent file in a repo, prefer .codex/goals.md unless the project already has a goals, roadmap, or planning document.

Persistent goal files should include:

# Goals

## Active
- [ ] ...

## Completed
- [x] ...

## Blocked
- [!] ...

Keep persistent files tidy and avoid storing transient implementation chatter.

Response Style

Keep goals useful and low-friction:

• Be concise.
• Use concrete verbs.
• Preserve the user's language when it captures intent well.
• Ask a question only when the goal cannot be inferred safely.
• Avoid over-planning exploratory or conversational requests.
• When the user asks only to see goals, do not start implementation.