
<!-- BACKLOG.MD MCP GUIDELINES START -->

<CRITICAL_INSTRUCTION>

## BACKLOG WORKFLOW INSTRUCTIONS

This project uses Backlog.md MCP for all task and project management activities.

**CRITICAL GUIDANCE**

- If your client supports MCP resources, read `backlog://workflow/overview` to understand when and how to use Backlog for this project.
- If your client only supports tools or the above request fails, call `backlog.get_backlog_instructions()` to load the tool-oriented overview. Use the `instruction` selector when you need `task-creation`, `task-execution`, or `task-finalization`.

- **First time working here?** Read the overview resource IMMEDIATELY to learn the workflow
- **Already familiar?** You should have the overview cached ("## Backlog.md Overview (MCP)")
- **When to read it**: BEFORE creating tasks, or when you're unsure whether to track work

These guides cover:
- Decision framework for when to create tasks
- Search-first workflow to avoid duplicates
- Links to detailed guides for task creation, execution, and finalization
- MCP tools reference

You MUST read the overview resource to understand the complete workflow. The information is NOT summarized here.

</CRITICAL_INSTRUCTION>

<!-- BACKLOG.MD MCP GUIDELINES END -->

## Available Skills

Five Claude Code skills are installed in this repo's dev container. Each maps to a phase of the feature lifecycle.

| Skill | Invoke | When to use |
|-------|--------|-------------|
| **grill-me** | `/grill-me` | Before implementing — stress-tests a design through sequential questioning |
| **to-prd** | `/to-prd` | After a planning conversation — formalises context into a GitHub issue PRD |
| **ubiquitous-language** | `/ubiquitous-language` | When domain terms are drifting or ambiguous — builds/updates `UBIQUITOUS_LANGUAGE.md` |
| **tdd** | `/tdd` | During implementation — enforces vertical-slice TDD (one test → one impl → repeat) |
| **improve-codebase-architecture** | `/improve-codebase-architecture` | During refactoring — surfaces shallow modules and proposes deepening opportunities |

### Typical session chains

**Feature planning:**
`/grill-me` → `/to-prd` → `/ubiquitous-language`

**Implementation:**
`/tdd` (+ `/grill-me` if a design fork appears mid-session)

**Refactoring:**
`/improve-codebase-architecture` → `/grill-me` → `/tdd` → `/ubiquitous-language`

### First time setting up?

New containers install all skills automatically via the Dockerfile. If you're in an existing container, run:

```bash
bash .devcontainer/backend/install-claude-skills.sh
```

## Type Safety

All new code must pass `pyright` with zero errors under `typeCheckingMode = strict`.
Use Optional over | None
Annotate all function return types. Use `dict[str, Any]` for untyped external API
payloads — never bare `dict`. Add `pandas-stubs` when introducing pandas to a module.