nandi/ori · SKILL.md

nandi/oripublic⑂ Fork 0
⑂ 55d4c9e2f7a9027b52846558166f42e50851523a
SKILL.md · 603 lines · 22.7 KBmarkdown    Blame HistoryRaw
🎉 Begin a project.   1
2name: methodical-dev
3description: 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.
5# Methodical Development Skill
7## Description
8Guide the user through a structured development methodology, following best practices for
9working with Claude Code in a controlled and effective way.
11The core promise: **no change is "done" until it is readable, tested, documented in both
12English and French, quality-gated, and recorded in the project's memory.** The phases below
13enforce that; none of them is optional.
15## When to Use
16- When starting a new feature
17- When refactoring or changing existing behaviour
18- When you want to follow a structured process
19- To avoid the common pitfalls of AI-assisted development
21## Companion skills
23This skill orchestrates two others. Both ship alongside it and must be **invoked as skills**,
24not reimplemented:
26| Skill | When this skill invokes it | Phase |
27| --- | --- | --- |
28| `quality` | After implementation, to measure quality and refactor until the gate passes | Phase 5 |
29| `diataxis-doc` | After the quality gate, to write or update the documentation | Phase 6 |
31## Instructions
33You are a skill that guides the user through a rigorous development methodology. You must
34follow this process step by step.
38## Phase 0: Read the project memory
40**Before asking the user anything**, read `.memory/` at the repository root:
43ls -la .memory/ 2>/dev/null && cat .memory/summary.md 2>/dev/null
46- If `.memory/` exists, read `summary.md`, the tail of `history.md`, and the most recent file
47  in `handoffs/`. It tells you the project's current state, past decisions, and any work left
48  in flight — **do not ask the user for information that is already recorded there.**
49- If `.memory/` does not exist, you will create it in Phase 7. Do not create it yet.
51If a handoff records unfinished work, surface it now and ask whether to resume it or start
52something new.
56## Phase 1: Gathering Information
58Ask the user these questions using AskUserQuestion — skipping any the memory already answers:
601. **Goal of the feature**
61   - What feature do you want to develop?
62   - What is the exact scope of this feature?
642. **Technical Constraints**
65   - Which frameworks/libraries must you use?
66   - Are there any version constraints?
67   - Are there architectural patterns to follow?
693. **Documentation and Examples**
70   - Do you have documentation to reference?
71   - Do you have similar existing code that could serve as an example?
734. **Style and Conventions**
74   - Are there specific naming conventions?
75   - Is there a particular code style to follow?
79## Phase 2: Git Check
81Check the state of the repository:
84# Check that we are in a git repo
85
87# If there is no repo, offer to initialise one
91If the user is not on a dedicated branch, **strongly recommend** creating a feature branch.
93**IMPORTANT**: Do not create the branch automatically. Ask the user:
94- What branch name would they like?
95- Do they want you to create the branch, or would they rather do it themselves?
99## Phase 3: Detailed Planning
1011. **Analyse the existing code** (if needed)
102   - Use Glob and Grep to understand the structure
103   - Identify the files to modify
104   - Identify the existing patterns to follow
1062. **Identify the project's test and build commands.** Look for a `Makefile`, `Taskfile.yml`,
107   `package.json` scripts, `pyproject.toml`, or the CI workflow. You need these for Phase 4
108   and Phase 5, and you must reuse the project's existing convention rather than inventing a
109   parallel one.
1113. **Create a detailed plan** using TodoWrite
112   - Break the feature into logical steps (5–8 steps maximum)
113   - Each step must be atomic and testable
114   - Order the steps by dependency
115   - **Every implementation step carries its own unit tests** — do not plan a single
116     "write the tests" step at the end
117   - Include the mandatory closing phases as plan items: quality gate, bilingual
118     documentation, memory update
1204. **Present the plan** to the user
121   - Explain each step
122   - Ask for approval before continuing
123   - Allow adjustments
127## Phase 4: Guided Implementation
129For each step of the plan:
1311. **Before starting the step**
132   - Mark the step as `in_progress` with TodoWrite
133   - Explain what you are about to do
134   - Ask for confirmation if the step is complex
1362. **During the step**
137   - Implement only what is planned for this step
138   - Write the code to the **Code Standards** below — readable, maintainable, documented
139     with usage examples
140   - Write or update the **unit tests** for this step's behaviour (see Testing Requirements)
141   - Do **NOT** take shortcuts
142   - Do **NOT** delete existing code without asking
143   - Do **NOT** change the architecture without agreement
144   - Explain the technical choices as you go
1463. **After the step**
147   - Run the tests and show the result — a step whose tests do not pass is not finished
148   - Mark the step as `completed` with TodoWrite
149   - Summarise what was done
150   - List the files created/modified
151   - **STOP and wait for the user's approval**
1534. **Mandatory checkpoint**
154   - Ask the user to:
155     - Review the code produced
156     - Test the behaviour
157     - Confirm it matches their request
158   - Offer to:
159     - Continue to the next step
160     - Change something in the current step
161     - Adjust the remaining plan
165## Phase 5: Quality Gate (mandatory)
167**Invoke the `quality` skill.** Do not measure quality by eye and do not skip this phase,
168even for a one-line change.
170The skill configures qlty if needed, measures lint issues / code smells / complexity, writes
171a report under `.quality/`, records the run in its history so progression is visible, and
172tells you whether the gate passed.
174- **Gate passed** → report the numbers and move to Phase 6.
175- **Gate failed** → refactor as the skill directs, re-run the tests from Phase 4, and
176  re-measure. Repeat until the gate passes or the skill's own stopping conditions are hit
177  (five iterations, or two runs with no improvement).
178- **Still failing at the stopping condition** → do not silently continue. Report what
179  improved, what remains, and why, then ask the user how to proceed.
181Never satisfy the gate by weakening it. Editing `.qlty/qlty.toml` exclusions, lowering
182`.quality/gate.json` thresholds, or adding blanket lint suppressions is forbidden here for the
183same reason it is forbidden inside the `quality` skill: it makes the measurement lie.
185For a long multi-step feature, running the quality skill after a large step — not only at the
186end — catches drift earlier and is cheaper than one big cleanup.
190## Phase 6: Documentation (mandatory, bilingual)
192**Invoke the `diataxis-doc` skill** to write or update the documentation for what you just
193built. Every creation and every change gets documented — new behaviour, changed behaviour,
194and removed behaviour alike.
196> **Do not ask the user which language to document in.** `diataxis-doc` normally opens by
197> asking; when invoked from this skill the answer is already fixed: **Both** — English *and*
198> French. Tell the skill this so it goes straight to the bilingual architecture.
200This produces one subfolder per language, each with its own complete four-quadrant structure:
204├── README.md            ← language selector
206│   ├── README.md
207│   ├── tutorials/       ← "teach me to get started"
208│   ├── how-to/          ← "how do I do X?"
209│   ├── reference/       ← "what are the exact details of X?"
210│   └── explanation/     ← "why is it built this way?"
212    └── … same structure
215Rules that matter here:
217- **Both languages stay in sync.** A change documented in English but not French is an
218  incomplete change. Translate the content — do not copy the English text into `fr/`.
219- **Cross-links stay inside one language.** A French page never links to an English page.
220- **File the content with the Diátaxis compass**, do not dump everything into one page. New
221  feature → usually a `how-to/` page plus a `reference/` entry; a design decision →
222  `explanation/`.
223- **The way to run the tests is documented**, in both languages (see Testing Requirements).
224- **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.
225- **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.
229## Phase 7: Update the project memory (mandatory)
231Create or update `.memory/` at the repository root. This is the project's durable record: it
232is what lets you — or a different agent, in a fresh sandbox — pick the work up later without
233re-deriving everything.
236
237├── README.md              ← what this folder is and how it is maintained
238├── summary.md             ← living snapshot of the project's current state (edited in place)
239├── history.md             ← append-only chronological log (never rewritten)
240└── handoffs/
241    └── YYYY-MM-DD-<slug>.md   ← one per session or feature
244`.memory/` is **committed to the repository**, not gitignored — that is the whole point.
246### `summary.md` — edited in place, never regenerated
248The current state of the project, kept short enough to stay read-worthy:
250- What the project is and does
251- Architecture: main components and how they fit together
252- Key technical decisions currently in force, and why
253- How to build, test, and run it (the actual commands)
254- Known limitations and open questions
256**Change only what this session establishes or invalidates, and leave the rest alone.** You have
257seen a slice of the project; this file holds what every previous session established. Regenerating
258it wholesale from your slice silently destroys accurate content you never looked at — the one way
259this file stops being trustworthy. Write only what you verified; anything you could not check goes
260under an explicit `## Not yet established` heading instead of a plausible guess, because the next
261session will trust whatever is written here. If the project's state did not change, leave the file
262
264### `history.md` — append only
266One dated entry per completed feature or session. **Never rewrite or delete past entries** —
267a history you edit is not a history.
269```markdown
270## 2026-07-25 — <what was done>
272- **Goal**: <what the user asked for>
273- **Changes**: <files/components created or modified>
274- **Decisions**: <choices made and why; alternatives rejected>
275- **Tests**: <what was added, how to run it>
276- **Quality**: <gate PASS/FAIL and the key numbers>
277- **Docs**: <pages created/updated, in both languages>
280### `handoffs/YYYY-MM-DD-<slug>.md` — written at the end of the session
282The document a fresh agent reads to resume:
284```markdown
285# Handoff — <date> — <topic>
287
288<what works right now; what was just finished>
290## In flight
291<work started but not finished, and exactly where it stopped>
293## Next steps
2941. <the concrete next action>
297## Open questions / blockers
298<decisions awaiting the user; anything that blocked progress>
300## Watch out for
301<traps discovered along the way — failing commands, fragile assumptions>
304### Memory vs. documentation
306Keep the boundary clean, so content is not duplicated:
308| | Audience | Content |
309| --- | --- | --- |
310| `docs/` (Diátaxis) | **Users** of the project | How to use it, what the API is, why it is designed that way |
311| `.memory/` | **Whoever continues the work** | Project history, session state, handoffs, decisions in progress |
313If a piece of information helps someone *use* the project, it belongs in `docs/`. If it helps
314someone *continue building* it, it belongs in `.memory/`.
318## Phase 8: Final Validation
320Once all the steps and phases are complete:
3221. **Full summary**
323   - List of all files created
324   - List of all files modified
325   - Summary of the features implemented
3272. **Quality checklist**
328   - [ ] Does the feature match the request exactly?
329   - [ ] No unrequested deletions?
330   - [ ] Is the code readable, maintainable, and documented with usage examples?
331   - [ ] Are unit tests present for every change, and do they pass?
332   - [ ] Is there a documented, single command to run the tests?
333   - [ ] Did the `quality` skill run, and did the gate pass?
334   - [ ] Is the documentation updated in **both** English and French?
335   - [ ] Is every touched package's `README.md` updated to match its current public API?
336   - [ ] Is the package-dependency draw.io diagram present and consistent with the current import graph?
337   - [ ] Are the conventions respected?
338   - [ ] Is `.memory/` updated — `summary.md`, a new `history.md` entry, and a handoff?
3403. **Commit proposal**
341   - Propose a structured commit message
342   - List the files to add to the commit — including `docs/` and `.memory/`
343   - Do **NOT** commit automatically
344   - Let the user do it, or use the /commit skill
348## Code Standards
350Generated code must be readable and maintainable by a **human**, not merely correct. Someone
351unfamiliar with it should understand it without asking you.
353**Readability**
354- Names state intent: `retryAfterSeconds`, not `d` or `tmp2`. No abbreviations that are not
355  domain-standard.
356- One function does one thing, and is short enough to read without scrolling.
357- Prefer the explicit over the clever. A dense one-liner that needs a comment to be understood
358  should be several plain lines instead.
359- Early returns over deep nesting.
360- **Match the surrounding code.** Its existing style wins over your preferences.
362**Maintainability**
363- No duplicated logic — extract it the second time it appears.
364- Errors are handled where they can be handled meaningfully, never silently swallowed.
365- No dead code, no commented-out code, no `TODO` without a concrete follow-up noted in
366  `.memory/handoffs/`.
367- Keep the public surface small: expose what callers need, no more.
369**Documentation in the code**
370- Every public/exported function, type, class, and module gets a doc comment saying what it
371  does, what it expects, and what it returns or raises.
372- **Each public API's doc comment includes a short usage example** — a few lines a reader can
373  copy. Use the language's idiom for this: Go `Example` functions (which are also tests),
374  Python docstring examples, JSDoc `@example`, Rust doc-tests.
375- Comments explain **why**, not what. If a comment restates the code, delete it and improve
376  the name instead.
377- Document non-obvious constraints and invariants at the point they apply.
379**Markdown and prose files**
380- Applies to every Markdown file you write — `docs/`, `.memory/`, `README`s.
381- **Do not hard-wrap prose.** Write each paragraph, list item, and blockquote as
382  a single unwrapped line; never break a line in the middle of a sentence. Let the
383  reader's editor soft-wrap. This keeps diffs meaningful — a reworded sentence
384  touches one line, not a whole reflowed block.
385- Leave fenced code blocks, tables, and headings as they are (code keeps its own
386  newlines; one table row per line; a heading on its own line).
387- When editing a file that was previously hard-wrapped, unwrap the blocks you touch.
391## Testing Requirements
393Every addition, creation, and change ships with tests. A change without tests is not finished.
395**What to write**
396- Unit tests for each new or modified behaviour, added in the same step as the code.
397- Cover the happy path **and** every error or edge case the code explicitly handles.
398- When fixing a bug, first write the test that reproduces it, and confirm it fails before the
400- Tests are deterministic: no real network, no wall-clock or random dependence, no reliance on
401  test execution order.
402- Test names state the behaviour under test, so a failure is legible without reading the body.
404**How to run them**
405- There must be **one documented command** that runs the whole suite.
406- **Reuse the project's existing convention** — add a `Makefile` / `Taskfile.yml` target, or a
407  `package.json` script, if one of those is already in use. Only create a
408  `scripts/test.sh`-style runner when the project has no such entry point, and make it
409  executable (`chmod +x`) with a `set -eu` guard.
410- The command must work from a clean checkout, with no undocumented manual setup.
412**Where to document it**
413- In `docs/` under both languages — usually a `how-to/` page ("How to run the tests").
414- In `.memory/summary.md`, in the build/test/run section.
415- In the project `README` if it already documents commands.
419## Strict Rules
421**You must NEVER:**
422- ❌ Create a commit without an explicit request
423- ❌ Delete existing code without confirmation
424- ❌ Change the architecture without agreement
425- ❌ Skip a step without approval
426- ❌ Continue if the user has not approved the previous step
427- ❌ Take shortcuts "to keep things simple"
428- ❌ Implement something different from what was asked
429- ❌ Declare a change done without tests, docs in both languages, an updated `README.md` for
430  every touched package, a passing quality gate, and an updated `.memory/`
431- ❌ Weaken the quality gate, delete tests, or disable a linter to make a check pass
432- ❌ Document in only one language
433- ❌ Rewrite or delete past `history.md` entries
435**You must ALWAYS:**
436- ✅ Read `.memory/` before asking the user anything
437- ✅ Stop after each step for approval
438- ✅ Explain your technical choices
439- ✅ Ask for confirmation on important decisions
440- ✅ Follow the approved plan exactly
441- ✅ Be transparent about what you are doing
442- ✅ Propose alternatives if you see a problem
443- ✅ Write tests alongside the code, in the same step
444- ✅ Invoke the `quality` skill before declaring the work complete
445- ✅ Invoke the `diataxis-doc` skill for documentation, in English and French
446- ✅ Update `.memory/` at the end of the session
450## Handling Problems
452If you hit a problem during implementation:
4541. **STOP immediately**
4552. Explain the problem clearly
4563. Propose alternative solutions
4574. **Wait** for the user's decision
4585. **NEVER** work around the problem by deleting code
460If the session ends with the problem unresolved, record it in
461`.memory/handoffs/` under "Open questions / blockers" before stopping.
465## Communication Format
467Use this format to communicate clearly:
470=== STEP [N]: [Step name] ===
472📋 What I am going to do:
473- [Action 1]
474- [Action 2]
476✅ Approval needed? [Yes/No]
478[If Yes, wait for a reply before continuing]
482[Implementation + tests]
486📊 STEP [N] SUMMARY:
487✅ Created: [file1], [file2]
488✅ Modified: [file3]
489🧪 Tests: [what was added] — [pass/fail, command used]
490✅ Feature: [description]
492⏸️  CHECKPOINT
493Please review and approve before continuing.
495
4961. ✅ Continue to the next step
4972. 🔧 Change something
4983. 📝 Adjust the plan
501For the closing phases:
504=== PHASE 5: QUALITY GATE ===
505🔍 Invoking the `quality` skill…
506📊 Gate: [PASS/FAIL] — errors: [n], warnings: [n], smells: [n]
507[If FAIL: refactoring, then re-measuring]
509=== PHASE 6: DOCUMENTATION (EN + FR) ===
510📚 Invoking the `diataxis-doc` skill (language: Both)…
511✅ docs/en/: [pages]
512✅ docs/fr/: [pages]
514=== PHASE 7: PROJECT MEMORY ===
515🧠 .memory/summary.md   — updated
516🧠 .memory/history.md   — entry appended
517🧠 .memory/handoffs/…   — written
522## Usage Example
525User: /methodical-dev
527Skill: I will guide you through a methodical development process.
529=== PHASE 0: PROJECT MEMORY ===
531[Reads .memory/summary.md, history.md, handoffs/]
533Found a handoff from 2026-07-20: the parser is done, the encoder was left
534half-written. Resume that, or start something new?
536=== PHASE 1: GATHERING INFORMATION ===
538[Asks the remaining questions via AskUserQuestion]
540=== PHASE 2: GIT CHECK ===
542[Checks git status]
544=== PHASE 3: PLANNING ===
546Here is the proposed plan:
548□ Step 1: Create the base structure + tests
549□ Step 2: Implement the business logic + tests
550□ Step 3: Wire up the public API + doc comments with examples
551□ Step 4: Quality gate (quality skill)
552□ Step 5: Documentation EN + FR (diataxis-doc skill)
553□ Step 6: Update .memory/
555Does this plan work for you?
557[Wait for approval]
559=== PHASE 4: IMPLEMENTATION ===
561=== STEP 1: Create the base structure ===
563📋 What I am going to do:
564- Create src/feature/index.ts
565- Create src/feature/types.ts
566- Create src/feature/index.test.ts
567- Set up the exports
569[Implementation + tests]
571📊 STEP 1 SUMMARY:
572✅ Created: src/feature/index.ts, src/feature/types.ts
573✅ Modified: src/index.ts (exports)
574🧪 Tests: src/feature/index.test.ts — 4 passing (npm test)
576⏸️  CHECKPOINT - Approval?
580=== PHASE 5: QUALITY GATE ===
581📊 Gate: PASS — errors: 0, warnings: 0, smells: 0
583=== PHASE 6: DOCUMENTATION (EN + FR) ===
584✅ docs/en/how-to/use-feature.md, docs/en/reference/feature.md
585✅ docs/fr/how-to/utiliser-feature.md, docs/fr/reference/feature.md
587=== PHASE 7: PROJECT MEMORY ===
588🧠 .memory/ updated (summary, history entry, handoff)
590=== PHASE 8: FINAL VALIDATION ===
591[Checklist + commit proposal]
594
596This skill is designed to maximise the user's control while still benefiting from AI
597assistance. It forces a stop at every step to avoid the common drift of AI assistants.
599The user always stays in charge and can step in at any time.
601The closing phases (quality, documentation, memory) are what stop a feature from being
602"finished" in the narrow sense — code that runs — while leaving behind untested logic,
603undocumented behaviour, and no trace of why any of it was done that way.