> ## Documentation Index
> Fetch the complete documentation index at: https://meganharrisonconsulting.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Using Matt Pocock Skills with Codex

> A practical guide to choosing and using the Matt Pocock workflow skills available in Codex.

# Using Matt Pocock Skills with Codex

The Matt Pocock skills give Codex a structured way to turn an idea into a
reviewed change: clarify the problem, make a spec, split the work, implement
it, and verify it. They are available globally to Codex in this workspace.

Use this page to choose a skill by the problem in front of you. Use the
[generated skills reference](/skills/index) when you need the exact source
instructions for a skill.

<Warning>
  This guide does not replace this repository's operating rules. `AGENTS.md`,
  the task done gate, the Linear-Codex process, and screenshot-based verification
  take precedence over any upstream skill instruction.
</Warning>

## Start here

Choose the smallest entry point that matches the work:

| Situation                                            | Start with        | Then                                                  |
| ---------------------------------------------------- | ----------------- | ----------------------------------------------------- |
| You are unsure which workflow fits                   | `ask-matt`        | Follow its recommended route.                         |
| You have an idea that needs pressure-testing         | `grill-with-docs` | `to-spec` → `to-tickets` → `implement`.               |
| You have a focused, already-understood change        | `implement`       | `code-review` and the repository's verification gate. |
| A defect is unclear, intermittent, or needs evidence | `diagnosing-bugs` | `tdd` or `implement` once the cause is proven.        |
| You need a throwaway answer to one design question   | `prototype`       | Bring the result back into the specification.         |
| The work is larger than one planning session         | `wayfinder`       | `to-spec` after the decision map is resolved.         |

Do not run every skill for every task. A small, known-path documentation or
copy edit should still use the repository's micro-change fast path. For normal
implementation and verification work in this repository, begin with the local
`qa-task` workflow and use the skills below when their specific problem applies.

## The primary flow

```text theme={null}
Idea or request
  -> grill-with-docs (when the idea is not ready)
  -> to-spec (when the outcome is agreed)
  -> to-tickets (when the work needs independent slices)
  -> implement (one slice at a time)
  -> code-review
  -> repository verification and publish gates
```

`handoff` is the bridge when the conversation needs to move to a fresh Codex
task. `prototype` is a temporary detour when a runnable experiment will answer
a question more reliably than discussion.

## Planning and discovery skills

| Skill             | Use it when                                                                              | What it produces                                              |
| ----------------- | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
| `ask-matt`        | You cannot tell which skill or sequence fits.                                            | A recommended workflow route.                                 |
| `grill-me`        | You want to sharpen an idea that is not tied to a repository.                            | A clarified plan in the conversation.                         |
| `grill-with-docs` | You need to sharpen a repository-backed idea and preserve decisions.                     | A clearer plan plus durable context/decision documentation.   |
| `grilling`        | You want a focused, rigorous challenge of an assumption, decision, or design.            | Exposed assumptions and resolved questions.                   |
| `to-spec`         | The conversation already contains an agreed outcome and needs a buildable specification. | A specification on the configured tracker.                    |
| `to-tickets`      | A specification needs independently deliverable vertical slices.                         | Ordered, dependency-aware tickets.                            |
| `wayfinder`       | The initiative is too uncertain or large to plan in one session.                         | A shared map of decision tickets, not implementation tickets. |
| `research`        | A question needs source-backed investigation before deciding or building.                | A cited Markdown research artifact.                           |

## Building and quality skills

| Skill                           | Use it when                                                                               | What it protects or produces                                                        |
| ------------------------------- | ----------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| `implement`                     | You have a scoped specification or agent-ready ticket.                                    | The implementation, built in small testable slices.                                 |
| `tdd`                           | You want a feature or bug fix driven by a failing behavior test.                          | Red-green-refactor implementation and regression coverage.                          |
| `diagnosing-bugs`               | A failure is hard to explain, intermittent, slow, or regressed.                           | A tight failing feedback loop, confirmed cause, and regression test.                |
| `code-review`                   | You need an independent review of a diff, branch, or pull request.                        | Standards and specification review findings.                                        |
| `improve-codebase-architecture` | You are looking for structural improvements that make the codebase easier to change.      | Deepening opportunities and a focused next design problem.                          |
| `resolving-merge-conflicts`     | A Git merge or rebase is already conflicted.                                              | A deliberate conflict resolution with validation.                                   |
| `prototype`                     | One behavior, state model, or interface needs a quick experiment before committing to it. | Throwaway code that answers the question; do not promote it directly to production. |

## Context, language, and learning skills

| Skill                  | Use it when                                                                    | What it produces                                       |
| ---------------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------ |
| `handoff`              | You need to continue in a fresh task without losing the important context.     | A compact handoff document for the next task.          |
| `domain-modeling`      | Domain vocabulary is fuzzy, overloaded, or disputed.                           | A sharper glossary and, when warranted, an ADR.        |
| `codebase-design`      | You are choosing a module boundary, interface, seam, or testability strategy.  | Shared deep-module vocabulary for the design decision. |
| `teach`                | You want Codex to teach a concept or skill within this workspace.              | A tailored explanation or learning path.               |
| `writing-great-skills` | You are creating or editing a skill and need it to be predictable and focused. | A better skill contract and instruction set.           |

## Intake and triage skills

| Skill                      | Use it when                                                                            | What it produces                                     |
| -------------------------- | -------------------------------------------------------------------------------------- | ---------------------------------------------------- |
| `setup-matt-pocock-skills` | You are configuring a new repository for this workflow suite for the first time.       | Tracker, triage-label, and domain-doc configuration. |
| `triage`                   | Incoming bug reports or feature requests need categorization and an agent-ready brief. | A reviewed, stateful triage outcome.                 |

<Note>
  For this repository, do not rerun `setup-matt-pocock-skills` to select a
  tracker without resolving the existing tracker-policy mismatch first. Full
  Codex tasks use Linear as the ownership source of truth, even where older
  documentation mentions GitHub Issues.
</Note>

## Repository-specific rules that always win

1. **Tracking:** Full-process work must have a Linear issue, task file, handoff,
   and milestone comments. Do not publish work tickets to GitHub merely because
   an upstream skill uses GitHub examples.
2. **Verification:** User-visible work needs actual end-to-end proof and a
   screenshot on the canonical route or artifact before it can be described as
   complete.
3. **Debugging:** Observe the running system and identify the first failing
   boundary before changing product code. `diagnosing-bugs` complements this
   requirement; it does not replace it.
4. **UI work:** Reuse the canonical shared route, primitive, or pattern first,
   and apply the Alleato product noise gate.
5. **Publishing:** The main application and this ReadMe site have separate Git
   boundaries. Commit and publish only the files owned by the task in the
   repository that owns them.

## Examples

### A new feature that affects several surfaces

Use `grill-with-docs` to settle the outcome. Use `to-spec` to capture the
accepted behavior, then `to-tickets` to create vertical slices. Run
`implement` for one slice at a time, followed by `code-review` and the
repository's browser and screenshot verification gates.

### A production bug with an unclear cause

Start with `diagnosing-bugs`, using browser/runtime evidence to establish a
repeatable failure. Once the first broken boundary is known, use `tdd` or
`implement` for the repair and keep the regression test.

### An ambiguous architectural improvement

Use `improve-codebase-architecture` to find a high-leverage opportunity. Use
`codebase-design` when choosing the seam, then return to the normal planning
and implementation flow only after the problem is concrete.

## See also

* [Skills reference](/skills/index) — generated source-level inventory of
  installed skills.
* [AI Engineering Playbook](/developer-docs/ai-engineering-playbook) — the
  repository's canonical task-tier and verification flow.