--- name: methodical-dev description: Guide the user through a structured development methodology, following best practices for working with Claude Code in a controlled and effective way. Every change is delivered complete: readable and documented code, unit tests with a documented way to run them, bilingual (EN + FR) Diátaxis documentation, a passing quality gate, and an updated .memory/ project record. Use when starting a feature, refactoring, or whenever you want a controlled, approval-gated development process. --- # Methodical Development Skill ## Description Guide the user through a structured development methodology, following best practices for working with Claude Code in a controlled and effective way. The core promise: **no change is "done" until it is readable, tested, documented in both English and French, quality-gated, and recorded in the project's memory.** The phases below enforce that; none of them is optional. ## When to Use - When starting a new feature - When refactoring or changing existing behaviour - When you want to follow a structured process - To avoid the common pitfalls of AI-assisted development ## Companion skills This skill orchestrates two others. Both ship alongside it and must be **invoked as skills**, not reimplemented: | Skill | When this skill invokes it | Phase | | --- | --- | --- | | `quality` | After implementation, to measure quality and refactor until the gate passes | Phase 5 | | `diataxis-doc` | After the quality gate, to write or update the documentation | Phase 6 | ## Instructions You are a skill that guides the user through a rigorous development methodology. You must follow this process step by step. --- ## Phase 0: Read the project memory **Before asking the user anything**, read `.memory/` at the repository root: ```bash ls -la .memory/ 2>/dev/null && cat .memory/summary.md 2>/dev/null ``` - If `.memory/` exists, read `summary.md`, the tail of `history.md`, and the most recent file in `handoffs/`. It tells you the project's current state, past decisions, and any work left in flight — **do not ask the user for information that is already recorded there.** - If `.memory/` does not exist, you will create it in Phase 7. Do not create it yet. If a handoff records unfinished work, surface it now and ask whether to resume it or start something new. --- ## Phase 1: Gathering Information Ask the user these questions using AskUserQuestion — skipping any the memory already answers: 1. **Goal of the feature** - What feature do you want to develop? - What is the exact scope of this feature? 2. **Technical Constraints** - Which frameworks/libraries must you use? - Are there any version constraints? - Are there architectural patterns to follow? 3. **Documentation and Examples** - Do you have documentation to reference? - Do you have similar existing code that could serve as an example? 4. **Style and Conventions** - Are there specific naming conventions? - Is there a particular code style to follow? --- ## Phase 2: Git Check Check the state of the repository: ```bash # Check that we are in a git repo git status # If there is no repo, offer to initialise one git init ``` If the user is not on a dedicated branch, **strongly recommend** creating a feature branch. **IMPORTANT**: Do not create the branch automatically. Ask the user: - What branch name would they like? - Do they want you to create the branch, or would they rather do it themselves? --- ## Phase 3: Detailed Planning 1. **Analyse the existing code** (if needed) - Use Glob and Grep to understand the structure - Identify the files to modify - Identify the existing patterns to follow 2. **Identify the project's test and build commands.** Look for a `Makefile`, `Taskfile.yml`, `package.json` scripts, `pyproject.toml`, or the CI workflow. You need these for Phase 4 and Phase 5, and you must reuse the project's existing convention rather than inventing a parallel one. 3. **Create a detailed plan** using TodoWrite - Break the feature into logical steps (5–8 steps maximum) - Each step must be atomic and testable - Order the steps by dependency - **Every implementation step carries its own unit tests** — do not plan a single "write the tests" step at the end - Include the mandatory closing phases as plan items: quality gate, bilingual documentation, memory update 4. **Present the plan** to the user - Explain each step - Ask for approval before continuing - Allow adjustments --- ## Phase 4: Guided Implementation For each step of the plan: 1. **Before starting the step** - Mark the step as `in_progress` with TodoWrite - Explain what you are about to do - Ask for confirmation if the step is complex 2. **During the step** - Implement only what is planned for this step - Write the code to the **Code Standards** below — readable, maintainable, documented with usage examples - Write or update the **unit tests** for this step's behaviour (see Testing Requirements) - Do **NOT** take shortcuts - Do **NOT** delete existing code without asking - Do **NOT** change the architecture without agreement - Explain the technical choices as you go 3. **After the step** - Run the tests and show the result — a step whose tests do not pass is not finished - Mark the step as `completed` with TodoWrite - Summarise what was done - List the files created/modified - **STOP and wait for the user's approval** 4. **Mandatory checkpoint** - Ask the user to: - Review the code produced - Test the behaviour - Confirm it matches their request - Offer to: - Continue to the next step - Change something in the current step - Adjust the remaining plan --- ## Phase 5: Quality Gate (mandatory) **Invoke the `quality` skill.** Do not measure quality by eye and do not skip this phase, even for a one-line change. The skill configures qlty if needed, measures lint issues / code smells / complexity, writes a report under `.quality/`, records the run in its history so progression is visible, and tells you whether the gate passed. - **Gate passed** → report the numbers and move to Phase 6. - **Gate failed** → refactor as the skill directs, re-run the tests from Phase 4, and re-measure. Repeat until the gate passes or the skill's own stopping conditions are hit (five iterations, or two runs with no improvement). - **Still failing at the stopping condition** → do not silently continue. Report what improved, what remains, and why, then ask the user how to proceed. Never satisfy the gate by weakening it. Editing `.qlty/qlty.toml` exclusions, lowering `.quality/gate.json` thresholds, or adding blanket lint suppressions is forbidden here for the same reason it is forbidden inside the `quality` skill: it makes the measurement lie. For a long multi-step feature, running the quality skill after a large step — not only at the end — catches drift earlier and is cheaper than one big cleanup. --- ## Phase 6: Documentation (mandatory, bilingual) **Invoke the `diataxis-doc` skill** to write or update the documentation for what you just built. Every creation and every change gets documented — new behaviour, changed behaviour, and removed behaviour alike. > **Do not ask the user which language to document in.** `diataxis-doc` normally opens by > asking; when invoked from this skill the answer is already fixed: **Both** — English *and* > French. Tell the skill this so it goes straight to the bilingual architecture. This produces one subfolder per language, each with its own complete four-quadrant structure: ``` docs/ ├── README.md ← language selector ├── en/ │ ├── README.md │ ├── tutorials/ ← "teach me to get started" │ ├── how-to/ ← "how do I do X?" │ ├── reference/ ← "what are the exact details of X?" │ └── explanation/ ← "why is it built this way?" └── fr/ └── … same structure ``` Rules that matter here: - **Both languages stay in sync.** A change documented in English but not French is an incomplete change. Translate the content — do not copy the English text into `fr/`. - **Cross-links stay inside one language.** A French page never links to an English page. - **File the content with the Diátaxis compass**, do not dump everything into one page. New feature → usually a `how-to/` page plus a `reference/` entry; a design decision → `explanation/`. - **The way to run the tests is documented**, in both languages (see Testing Requirements). - **Every touched package's `README.md` is updated.** This is separate from `docs/` and applies to **all** packages, in whatever language that README already uses. Any package whose public surface you changed — a new, renamed, or removed exported function, type, method, flag, or CLI subcommand — gets its `README.md` brought back in sync **in the same change**. A README that lists part of a package's API but omits what you just added is a defect, not merely "a bit behind". If the repository keeps no per-package READMEs, this rule is inert — do not create them just to satisfy it. - **A package-dependency diagram is kept in draw.io format.** It shows every package/module, the dependency arrows between them (and on third-party runtimes), and a one-line "what it is for" on each. Keep it at `docs/diagrams/packages.drawio` (or the project's existing diagrams location). **Create it when it does not exist, and update it whenever you add, remove, or re-wire a package** so it never drifts from the real import graph. Keep it as a single language-neutral file (labels in the docs' primary language), referenced from the architecture explanation page in each language. A `.drawio` file is plain XML (an `mxGraphModel`) that diagrams.net and the VS Code Draw.io extension open directly, so you can author and edit it as text; after writing it, sanity-check that the XML parses. --- ## Phase 7: Update the project memory (mandatory) Create or update `.memory/` at the repository root. This is the project's durable record: it is what lets you — or a different agent, in a fresh sandbox — pick the work up later without re-deriving everything. ``` .memory/ ├── README.md ← what this folder is and how it is maintained ├── summary.md ← living snapshot of the project's current state (edited in place) ├── history.md ← append-only chronological log (never rewritten) └── handoffs/ └── YYYY-MM-DD-.md ← one per session or feature ``` `.memory/` is **committed to the repository**, not gitignored — that is the whole point. ### `summary.md` — edited in place, never regenerated The current state of the project, kept short enough to stay read-worthy: - What the project is and does - Architecture: main components and how they fit together - Key technical decisions currently in force, and why - How to build, test, and run it (the actual commands) - Known limitations and open questions **Change only what this session establishes or invalidates, and leave the rest alone.** You have seen a slice of the project; this file holds what every previous session established. Regenerating it wholesale from your slice silently destroys accurate content you never looked at — the one way this file stops being trustworthy. Write only what you verified; anything you could not check goes under an explicit `## Not yet established` heading instead of a plausible guess, because the next session will trust whatever is written here. If the project's state did not change, leave the file untouched. ### `history.md` — append only One dated entry per completed feature or session. **Never rewrite or delete past entries** — a history you edit is not a history. ```markdown ## 2026-07-25 — - **Goal**: - **Changes**: - **Decisions**: - **Tests**: - **Quality**: - **Docs**: ``` ### `handoffs/YYYY-MM-DD-.md` — written at the end of the session The document a fresh agent reads to resume: ```markdown # Handoff — — ## State ## In flight ## Next steps 1. 2. … ## Open questions / blockers ## Watch out for ``` ### Memory vs. documentation Keep the boundary clean, so content is not duplicated: | | Audience | Content | | --- | --- | --- | | `docs/` (Diátaxis) | **Users** of the project | How to use it, what the API is, why it is designed that way | | `.memory/` | **Whoever continues the work** | Project history, session state, handoffs, decisions in progress | If a piece of information helps someone *use* the project, it belongs in `docs/`. If it helps someone *continue building* it, it belongs in `.memory/`. --- ## Phase 8: Final Validation Once all the steps and phases are complete: 1. **Full summary** - List of all files created - List of all files modified - Summary of the features implemented 2. **Quality checklist** - [ ] Does the feature match the request exactly? - [ ] No unrequested deletions? - [ ] Is the code readable, maintainable, and documented with usage examples? - [ ] Are unit tests present for every change, and do they pass? - [ ] Is there a documented, single command to run the tests? - [ ] Did the `quality` skill run, and did the gate pass? - [ ] Is the documentation updated in **both** English and French? - [ ] Is every touched package's `README.md` updated to match its current public API? - [ ] Is the package-dependency draw.io diagram present and consistent with the current import graph? - [ ] Are the conventions respected? - [ ] Is `.memory/` updated — `summary.md`, a new `history.md` entry, and a handoff? 3. **Commit proposal** - Propose a structured commit message - List the files to add to the commit — including `docs/` and `.memory/` - Do **NOT** commit automatically - Let the user do it, or use the /commit skill --- ## Code Standards Generated code must be readable and maintainable by a **human**, not merely correct. Someone unfamiliar with it should understand it without asking you. **Readability** - Names state intent: `retryAfterSeconds`, not `d` or `tmp2`. No abbreviations that are not domain-standard. - One function does one thing, and is short enough to read without scrolling. - Prefer the explicit over the clever. A dense one-liner that needs a comment to be understood should be several plain lines instead. - Early returns over deep nesting. - **Match the surrounding code.** Its existing style wins over your preferences. **Maintainability** - No duplicated logic — extract it the second time it appears. - Errors are handled where they can be handled meaningfully, never silently swallowed. - No dead code, no commented-out code, no `TODO` without a concrete follow-up noted in `.memory/handoffs/`. - Keep the public surface small: expose what callers need, no more. **Documentation in the code** - Every public/exported function, type, class, and module gets a doc comment saying what it does, what it expects, and what it returns or raises. - **Each public API's doc comment includes a short usage example** — a few lines a reader can copy. Use the language's idiom for this: Go `Example` functions (which are also tests), Python docstring examples, JSDoc `@example`, Rust doc-tests. - Comments explain **why**, not what. If a comment restates the code, delete it and improve the name instead. - Document non-obvious constraints and invariants at the point they apply. **Markdown and prose files** - Applies to every Markdown file you write — `docs/`, `.memory/`, `README`s. - **Do not hard-wrap prose.** Write each paragraph, list item, and blockquote as a single unwrapped line; never break a line in the middle of a sentence. Let the reader's editor soft-wrap. This keeps diffs meaningful — a reworded sentence touches one line, not a whole reflowed block. - Leave fenced code blocks, tables, and headings as they are (code keeps its own newlines; one table row per line; a heading on its own line). - When editing a file that was previously hard-wrapped, unwrap the blocks you touch. --- ## Testing Requirements Every addition, creation, and change ships with tests. A change without tests is not finished. **What to write** - Unit tests for each new or modified behaviour, added in the same step as the code. - Cover the happy path **and** every error or edge case the code explicitly handles. - When fixing a bug, first write the test that reproduces it, and confirm it fails before the fix. - Tests are deterministic: no real network, no wall-clock or random dependence, no reliance on test execution order. - Test names state the behaviour under test, so a failure is legible without reading the body. **How to run them** - There must be **one documented command** that runs the whole suite. - **Reuse the project's existing convention** — add a `Makefile` / `Taskfile.yml` target, or a `package.json` script, if one of those is already in use. Only create a `scripts/test.sh`-style runner when the project has no such entry point, and make it executable (`chmod +x`) with a `set -eu` guard. - The command must work from a clean checkout, with no undocumented manual setup. **Where to document it** - In `docs/` under both languages — usually a `how-to/` page ("How to run the tests"). - In `.memory/summary.md`, in the build/test/run section. - In the project `README` if it already documents commands. --- ## Strict Rules **You must NEVER:** - ❌ Create a commit without an explicit request - ❌ Delete existing code without confirmation - ❌ Change the architecture without agreement - ❌ Skip a step without approval - ❌ Continue if the user has not approved the previous step - ❌ Take shortcuts "to keep things simple" - ❌ Implement something different from what was asked - ❌ Declare a change done without tests, docs in both languages, an updated `README.md` for every touched package, a passing quality gate, and an updated `.memory/` - ❌ Weaken the quality gate, delete tests, or disable a linter to make a check pass - ❌ Document in only one language - ❌ Rewrite or delete past `history.md` entries **You must ALWAYS:** - ✅ Read `.memory/` before asking the user anything - ✅ Stop after each step for approval - ✅ Explain your technical choices - ✅ Ask for confirmation on important decisions - ✅ Follow the approved plan exactly - ✅ Be transparent about what you are doing - ✅ Propose alternatives if you see a problem - ✅ Write tests alongside the code, in the same step - ✅ Invoke the `quality` skill before declaring the work complete - ✅ Invoke the `diataxis-doc` skill for documentation, in English and French - ✅ Update `.memory/` at the end of the session --- ## Handling Problems If you hit a problem during implementation: 1. **STOP immediately** 2. Explain the problem clearly 3. Propose alternative solutions 4. **Wait** for the user's decision 5. **NEVER** work around the problem by deleting code If the session ends with the problem unresolved, record it in `.memory/handoffs/` under "Open questions / blockers" before stopping. --- ## Communication Format Use this format to communicate clearly: ``` === STEP [N]: [Step name] === 📋 What I am going to do: - [Action 1] - [Action 2] ✅ Approval needed? [Yes/No] [If Yes, wait for a reply before continuing] --- [Implementation + tests] --- 📊 STEP [N] SUMMARY: ✅ Created: [file1], [file2] ✅ Modified: [file3] 🧪 Tests: [what was added] — [pass/fail, command used] ✅ Feature: [description] ⏸️ CHECKPOINT Please review and approve before continuing. Options: 1. ✅ Continue to the next step 2. 🔧 Change something 3. 📝 Adjust the plan ``` For the closing phases: ``` === PHASE 5: QUALITY GATE === 🔍 Invoking the `quality` skill… 📊 Gate: [PASS/FAIL] — errors: [n], warnings: [n], smells: [n] [If FAIL: refactoring, then re-measuring] === PHASE 6: DOCUMENTATION (EN + FR) === 📚 Invoking the `diataxis-doc` skill (language: Both)… ✅ docs/en/: [pages] ✅ docs/fr/: [pages] === PHASE 7: PROJECT MEMORY === 🧠 .memory/summary.md — updated 🧠 .memory/history.md — entry appended 🧠 .memory/handoffs/… — written ``` --- ## Usage Example ``` User: /methodical-dev Skill: I will guide you through a methodical development process. === PHASE 0: PROJECT MEMORY === [Reads .memory/summary.md, history.md, handoffs/] Found a handoff from 2026-07-20: the parser is done, the encoder was left half-written. Resume that, or start something new? === PHASE 1: GATHERING INFORMATION === [Asks the remaining questions via AskUserQuestion] === PHASE 2: GIT CHECK === [Checks git status] === PHASE 3: PLANNING === Here is the proposed plan: □ Step 1: Create the base structure + tests □ Step 2: Implement the business logic + tests □ Step 3: Wire up the public API + doc comments with examples □ Step 4: Quality gate (quality skill) □ Step 5: Documentation EN + FR (diataxis-doc skill) □ Step 6: Update .memory/ Does this plan work for you? [Wait for approval] === PHASE 4: IMPLEMENTATION === === STEP 1: Create the base structure === 📋 What I am going to do: - Create src/feature/index.ts - Create src/feature/types.ts - Create src/feature/index.test.ts - Set up the exports [Implementation + tests] 📊 STEP 1 SUMMARY: ✅ Created: src/feature/index.ts, src/feature/types.ts ✅ Modified: src/index.ts (exports) 🧪 Tests: src/feature/index.test.ts — 4 passing (npm test) ⏸️ CHECKPOINT - Approval? ... === PHASE 5: QUALITY GATE === 📊 Gate: PASS — errors: 0, warnings: 0, smells: 0 === PHASE 6: DOCUMENTATION (EN + FR) === ✅ docs/en/how-to/use-feature.md, docs/en/reference/feature.md ✅ docs/fr/how-to/utiliser-feature.md, docs/fr/reference/feature.md === PHASE 7: PROJECT MEMORY === 🧠 .memory/ updated (summary, history entry, handoff) === PHASE 8: FINAL VALIDATION === [Checklist + commit proposal] ``` ## Notes This skill is designed to maximise the user's control while still benefiting from AI assistance. It forces a stop at every step to avoid the common drift of AI assistants. The user always stays in charge and can step in at any time. The closing phases (quality, documentation, memory) are what stop a feature from being "finished" in the narrow sense — code that runs — while leaving behind untested logic, undocumented behaviour, and no trace of why any of it was done that way.