Workspace Docs

---
name: workspace-docs
description: "Check workspace for problem specs and convention docs before writing code. Use when starting implementation tasks, fixing tests, or any code change to find format rules and constraints."
topic: Workspace Documentation
token_cost: 140
keywords:
  [
    implement,
    build,
    create,
    fix,
    task,
    exercise,
    feature,
    todo,
    spec,
    specification,
    requirements,
    instructions,
    bug,
    test,
    failing,
    review,
    refactor,
  ]
requires_tools: [read, find]
---

## When to use

Before writing code for a non-trivial task, check if the workspace has a problem specification or convention document.

## Rules

- These are cheap to read and often contain the exact format rules, edge cases, or constraints the tests assert
- Look for (in priority order): `.docs/instructions.md` and `.docs/instructions.append.md` (exercism-style problem specs)
- Also check: `AGENTS.md` / `CLAUDE.md` (agent-specific instructions at repo root)
- Also check: `README.md` in the current directory, `SPEC.md` / `SPECIFICATION.md`, and `docs/*.md`
- Use find to discover them (`*.md`, `.docs/*.md`, `AGENTS.md`) and read the relevant one
- Do this ONCE at the start of a task, not every turn
- If the spec disambiguates a failing test, that single read saves many debug iterations
- Skip for pure read-only questions — only invest the Read call when you are about to change code
- NEVER skip this step when about to write code — the spec often contains test constraints

## File locations

`.docs/instructions.md`, `.docs/instructions.append.md`, `AGENTS.md`, `CLAUDE.md`, `README.md`, `SPEC.md`, `SPECIFICATION.md`, `docs/*.md`.

## Example

Before coding: `find(".docs/*.md")` → finds `instructions.md` → `read(".docs/instructions.md")` reveals test constraints like "output must be sorted". Saves multiple debug iterations.