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.