Prohlížeč zdrojového kódu
.claude/skills/spec/SKILL.md
name: spec
description: >
Spec workflow for this Ruby portfolio app. Use this skill whenever starting work on any feature,
bug fix, code exploration, or question about how something works — always check docs/specs/ first
before reading source code. Also use when the user explicitly runs /spec or asks to write, update,
or review a spec. If the user asks "how does X work?", "what does Y do?", or "where is Z?",
check docs/specs/index.md before exploring the codebase.
Spec Workflow
Living spec files in docs/specs/ describe what features/components are and how they work.
Each spec is a permanent reference, not a task log.
Always read a relevant spec before exploring source code. Check docs/specs/index.md first
to find the right spec, then read it. Only go to the source if the spec doesn't answer the question.
- Index:
docs/specs/index.md - Template:
docs/specs/TEMPLATE.md - Naming:
docs/specs/<slug>.md— descriptive, no dates (e.g.scenario-runner.md)
Important: Overview and Behaviour sections describe intended goals and observable behaviour only —
implementation specifics (file paths, class names, config) belong in Implementation Notes.
Choosing a mode
When invoked via /spec, ask the user:
"Which mode?
- Prospective — new feature or planned fix (write spec → tests → implement → verify)
- Retrospective — document existing behaviour (read code → write spec → done)"
If $ARGUMENTS is provided, derive <slug> and <title> from it. Otherwise ask:
"What feature or component do you want to spec? Provide a short slug and a human-readable title."
Check if docs/specs/<slug>.md already exists before proceeding.
Prospective workflow
a. Draft Overview + Behaviour
Read docs/specs/TEMPLATE.md to understand the spec structure.
Collaborate with the user to draft the Overview and Behaviour sections. These sections must
describe intended behaviour and goals only — they should be idempotent (valid regardless of
implementation). Do not mention specific files, classes, config entries, or code changes in Overview
or Behaviour; those belong in Implementation Notes.
Present a draft and ask: "Does this capture the intended behaviour? If not, what should be adjusted
before we start making a plan?"
Iterate until the user approves.
b. Create the spec file
Create docs/specs/<slug>.md from the template, filling in the approved Overview and Behaviour.
Leave Implementation Notes blank for now.
Add an entry for the new spec to docs/specs/index.md — a one-line description matching the Overview.
c. Write implementation plan
Based on the Behaviour section, identify and list:
- Which files need to be created or changed
- The key technical approach and any non-obvious decisions
- Any risks or open questions
Present the plan and ask: "Does this approach look right? If not, what should be adjusted before
we write tests?"
Iterate until approved.
d. Write failing RSpec tests
Based on the Behaviour section and approved plan, write RSpec tests (in the appropriate spec file(s))
that describe the expected behaviour. The tests should fail at this point.
Present the tests and ask: "Do these tests cover the right scenarios? If not, what should be adjusted?"
Iterate until approved.
e. Implement the feature
Implement the feature to make the tests pass. Follow project conventions (see CLAUDE.md).
Present the implementation and ask: "Does this implementation look correct? If not, what are your
concerns? What should be adjusted?"
Iterate until approved.
f. Run tests
Run rspec (or the relevant spec file) to verify all tests pass. If any fail, fix them before
continuing.
g. Fill in Implementation Notes
Update docs/specs/<slug>.md — fill in the Implementation Notes section describing key
decisions, file locations, and anything non-obvious.
Present the completed spec and ask: "Does the spec accurately reflect what was built? If not, what
should be adjusted?"
Iterate until approved.
h. Finalize
Follow the Finalize steps below.
Retrospective workflow
a. Read existing code
Identify and read the relevant source files, controllers, services, models, and existing specs
related to <slug>. Also check if any related spec already exists in docs/specs/.
b. Draft the spec
Read docs/specs/TEMPLATE.md. Write docs/specs/<slug>.md describing the current behaviour —
what the component does, its inputs/outputs, edge cases, and references to existing tests. Overview
and Behaviour must capture goals and observable behaviour only; implementation specifics (file paths,
class names, config) belong in Implementation Notes.
Add an entry for the new spec to docs/specs/index.md — a one-line description matching the Overview.
Present the draft and ask: "Does this accurately describe the current behaviour? If not, what should
be adjusted?"
Iterate until the user approves.
c. Finalize
Follow the Finalize steps below.
Finalize
Cross-link related specs and CLAUDE.md
Read all existing specs in docs/specs/ (skip TEMPLATE.md and index.md). Identify any that are
meaningfully related to the new spec.
For each related spec:
- Add an entry under ## See Also in docs/specs/<slug>.md linking to it, with a one-line note on
the relationship.
- Add a reciprocal entry under ## See Also in the related spec linking back.
Then check CLAUDE.md for sections that cover the same area as this spec. Where a section would
benefit from a direct spec link, add one.
Done
Remind the user: "The spec is done. Don't forget to try it out. Ask me to commit when ready."
Do not commit without being explicitly asked by the user.