nandi/oripublic⑂ Fork 0

⑂ db7446cc6b52b6bd9196294c1e66e5eb56754d5e

forked from bots-garden/ori

🎉 Begin a project. 4edda86 · on db7446cc6b52b6bd9196294c1e66e5eb56754d5e · k33g · yesterday

SKILL.md · 603 lines · 22.7 KBmarkdown

Rendered Raw

Blame History Open raw

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:

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:

Goal of the feature
- What feature do you want to develop?
- What is the exact scope of this feature?
Technical Constraints
- Which frameworks/libraries must you use?
- Are there any version constraints?
- Are there architectural patterns to follow?
Documentation and Examples
- Do you have documentation to reference?
- Do you have similar existing code that could serve as an example?
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:

# 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

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
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.
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
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:

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
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
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
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-<slug>.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.

## 2026-07-25 — <what was done>

- **Goal**: <what the user asked for>
- **Changes**: <files/components created or modified>
- **Decisions**: <choices made and why; alternatives rejected>
- **Tests**: <what was added, how to run it>
- **Quality**: <gate PASS/FAIL and the key numbers>
- **Docs**: <pages created/updated, in both languages>

`handoffs/YYYY-MM-DD-<slug>.md` — written at the end of the session

The document a fresh agent reads to resume:

# Handoff — <date> — <topic>

## State
<what works right now; what was just finished>

## In flight
<work started but not finished, and exactly where it stopped>

## Next steps
1. <the concrete next action>
2. …

## Open questions / blockers
<decisions awaiting the user; anything that blocked progress>

## Watch out for
<traps discovered along the way — failing commands, fragile assumptions>

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:

Full summary
- List of all files created
- List of all files modified
- Summary of the features implemented
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?
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/, READMEs.
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:

STOP immediately
Explain the problem clearly
Propose alternative solutions
Wait for the user's decision
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.

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603


---
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-<slug>.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 — <what was done>

- **Goal**: <what the user asked for>
- **Changes**: <files/components created or modified>
- **Decisions**: <choices made and why; alternatives rejected>
- **Tests**: <what was added, how to run it>
- **Quality**: <gate PASS/FAIL and the key numbers>
- **Docs**: <pages created/updated, in both languages>
```

### `handoffs/YYYY-MM-DD-<slug>.md` — written at the end of the session

The document a fresh agent reads to resume:

```markdown
# Handoff — <date> — <topic>

## State
<what works right now; what was just finished>

## In flight
<work started but not finished, and exactly where it stopped>

## Next steps
1. <the concrete next action>
2. …

## Open questions / blockers
<decisions awaiting the user; anything that blocked progress>

## Watch out for
<traps discovered along the way — failing commands, fragile assumptions>
```

### 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.