@martinffx/atelier 1.2.1 → 1.3.0

package/skills/code-debug/SKILL.md

@@ -1,199 +0,0 @@
----
-name: code-debug
-description: >
-  Disciplined diagnosis loop for hard bugs and performance regressions.
-  Reproduce → minimise → hypothesise → instrument → fix → regression-test.
-  Use when user says "diagnose this" / "debug this", reports a bug, says
-  something is broken/throwing/failing, or describes a performance regression.
-user-invocable: true
----
-
-# Code Debug
-
-A discipline for hard bugs. Skip phases only when explicitly justified.
-
-When exploring the codebase, use the project's domain glossary to get a clear
-mental model of the relevant modules, and check ADRs in the area you're touching.
-
----
-
-## Phase 1 — Build a feedback loop
-
-**This is the skill.** Everything else is mechanical. If you have a fast,
-deterministic, agent-runnable pass/fail signal for the bug, you will find the
-cause — bisection, hypothesis-testing, and instrumentation all just consume
-that signal. If you don't have one, no amount of staring at code will save you.
-
-Spend disproportionate effort here. **Be aggressive. Be creative. Refuse to
-give up.**
-
-### Ways to construct one — try them in roughly this order
-
-1. **Failing test** at whatever seam reaches the bug — unit, integration, e2e.
-2. **Curl / HTTP script** against a running dev server.
-3. **CLI invocation** with a fixture input, diffing stdout against a known-good
-   snapshot.
-4. **Headless browser script** (Playwright / Puppeteer) — drives the UI,
-   asserts on DOM/console/network.
-5. **Replay a captured trace.** Save a real network request / payload / event
-   log to disk; replay it through the code path in isolation.
-6. **Throwaway harness.** Spin up a minimal subset of the system (one service,
-   mocked deps) that exercises the bug code path with a single function call.
-7. **Property / fuzz loop.** If the bug is "sometimes wrong output", run 1000
-   random inputs and look for the failure mode.
-8. **Bisection harness.** If the bug appeared between two known states (commit,
-   dataset, version), automate "boot at state X, check, repeat" so you can
-   `git bisect run` it.
-9. **Differential loop.** Run the same input through old-version vs new-version
-   (or two configs) and diff outputs.
-10. **HITL bash script.** Last resort. If a human must click, drive _them_ with
-    a structured script so the loop is still structured. Captured output feeds
-    back to you.
-
-Build the right feedback loop, and the bug is 90% fixed.
-
-### Iterate on the loop itself
-
-Treat the loop as a product. Once you have _a_ loop, ask:
-
-- Can I make it faster? (Cache setup, skip unrelated init, narrow the test scope.)
-- Can I make the signal sharper? (Assert on the specific symptom, not "didn't crash".)
-- Can I make it more deterministic? (Pin time, seed RNG, isolate filesystem, freeze network.)
-
-A 30-second flaky loop is barely better than no loop. A 2-second deterministic
-loop is a debugging superpower.
-
-### Non-deterministic bugs
-
-The goal is not a clean repro but a **higher reproduction rate**. Loop the
-trigger 100×, parallelise, add stress, narrow timing windows, inject sleeps.
-A 50%-flake bug is debuggable; 1% is not — keep raising the rate until it's
-debuggable.
-
-### When you genuinely cannot build a loop
-
-Stop and say so explicitly. List what you tried. Ask the user for:
-(a) access to whatever environment reproduces it,
-(b) a captured artifact (HAR file, log dump, core dump, screen recording with timestamps), or
-(c) permission to add temporary production instrumentation.
-
-Do **not** proceed to hypothesise without a loop.
-
-**Do not proceed to Phase 2 until you have a loop you believe in.**
-
----
-
-## Phase 2 — Reproduce
-
-Run the loop. Watch the bug appear.
-
-Confirm:
-
-- [ ] The loop produces the failure mode the **user** described — not a different failure that happens to be nearby. Wrong bug = wrong fix.
-- [ ] The failure is reproducible across multiple runs (or, for non-deterministic bugs, reproducible at a high enough rate to debug against).
-- [ ] You have captured the exact symptom (error message, wrong output, slow timing) so later phases can verify the fix actually addresses it.
-
-**Do not proceed until you reproduce the bug.**
-
----
-
-## Phase 3 — Hypothesise
-
-Generate **3–5 ranked hypotheses** before testing any of them. Single-hypothesis
-generation anchors on the first plausible idea.
-
-Each hypothesis must be **falsifiable**: state the prediction it makes.
-
-> Format: "If `<X>` is the cause, then `<changing Y>` will make the bug disappear / `<changing Z>` will make it worse."
-
-If you cannot state the prediction, the hypothesis is a vibe — discard or sharpen it.
-
-**Show the ranked list to the user before testing.** They often have domain
-knowledge that re-ranks instantly ("we just deployed a change to #3"), or know
-hypotheses they've already ruled out. Cheap checkpoint, big time saver. Don't
-block on it — proceed with your ranking if the user is AFK.
-
----
-
-## Phase 4 — Instrument
-
-Each probe must map to a specific prediction from Phase 3. **Change one variable
-at a time.**
-
-Tool preference:
-
-1. **Debugger / REPL inspection** if the env supports it. One breakpoint beats ten logs.
-2. **Targeted logs** at the boundaries that distinguish hypotheses.
-3. Never "log everything and grep".
-
-**Tag every debug log** with a unique prefix, e.g. `[DEBUG-a4f2]`. Cleanup at
-the end becomes a single grep. Untagged logs survive; tagged logs die.
-
-**Perf branch.** For performance regressions, logs are usually wrong. Instead:
-establish a baseline measurement (timing harness, `performance.now()`, profiler,
-query plan), then bisect. Measure first, fix second.
-
----
-
-## Phase 5 — Fix + regression test
-
-Write the regression test **before the fix** — but only if there is a
-**correct seam** for it.
-
-A correct seam is one where the test exercises the **real bug pattern** as it
-occurs at the call site. If the only available seam is too shallow (single-caller
-test when the bug needs multiple callers, unit test that can't replicate the
-chain that triggered the bug), a regression test there gives false confidence.
-
-**If no correct seam exists, that itself is the finding.** Note it. The codebase
-architecture is preventing the bug from being locked down. Flag this for the
-next phase.
-
-If a correct seam exists:
-
-1. Turn the minimised repro into a failing test at that seam.
-2. Watch it fail.
-3. Apply the fix.
-4. Watch it pass.
-5. Re-run the Phase 1 feedback loop against the original (un-minimised) scenario.
-
----
-
-## Phase 6 — Cleanup + post-mortem
-
-Required before declaring done:
-
-- [ ] Original repro no longer reproduces (re-run the Phase 1 loop)
-- [ ] Regression test passes (or absence of seam is documented)
-- [ ] All `[DEBUG-...]` instrumentation removed (`grep` the prefix)
-- [ ] Throwaway prototypes deleted (or moved to a clearly-marked debug location)
-- [ ] The hypothesis that turned out correct is stated in the commit / PR message — so the next debugger learns
-
-**Then ask: what would have prevented this bug?**
-
-If the answer involves architectural change (no good test seam, tangled callers,
-hidden coupling) flag this as a codebase health finding for the team.
-
----
-
-## References
-
-- **Language-specific tools** → `references/language-tools.md`
-- **Common bug patterns** → `references/bug-patterns.md`
-- **Logging & techniques** → `references/techniques.md`
-
-## Output Format
-
-After each debugging session, summarise:
-
-```
-## Debug Summary
-
-**Problem:** [One sentence]
-**Root Cause:** [What actually was wrong]
-**Fix:** [How you fixed it]
-**Verification:** [Test results]
-**Prevention:** [Regression test added? Architectural finding?]
-```
-
-This helps future-you understand what happened.

package/skills/code-docs/SKILL.md

@@ -1,171 +0,0 @@
----
-name: code-docs
-description: >
-  Documentation generation for code projects. Use when updating docs, writing README, generating
-  API docs, creating changelog, or when the user mentions documentation, docs, readme, api docs,
-  or any documentation task.
-user-invocable: true
----
-
-# Code Docs
-
-Documentation generation and maintenance for code projects.
-
-## When to Document
-
-**Always update docs when:**
-- Adding new features
-- Changing existing behavior
-- Updating configuration
-- Breaking changes
-
-**Docs should live:**
-- Near the code (docstrings, comments)
-- In the repo (README, docs folder)
-- Generated (API docs, type docs)
-
----
-
-## Doc Types
-
-### README
-
-Project overview, setup, usage. See references/readme-structure.md
-
-**Template:**
-```markdown
-# Project Name
-
-Brief description (one line).
-
-## Quick Start
-
-3-5 commands to get running.
-
-## Installation
-
-Detailed setup steps.
-
-## Usage
-
-Code examples.
-
-## API
-
-Link to full API docs.
-
-## Contributing
-
-How to contribute.
-
-## License
-```
-
-### API Documentation
-
-See references/api-docs.md for:
-- TypeDoc (JavaScript/TypeScript)
-- Sphinx (Python)
-- godoc (Go)
-- JSDoc (JavaScript)
-
-### Changelog
-
-See references/changelog.md for Keep a Changelog format.
-
-**Sections:**
-- Added
-- Changed
-- Deprecated
-- Removed
-- Fixed
-- Security
-
-### Architecture Docs
-
-See references/architecture-docs.md for:
-- ADRs (Architecture Decision Records)
-- Diagrams
-- System overviews
-
----
-
-## Generation Commands
-
-### TypeScript/JavaScript
-
-```bash
-# TypeDoc
-npx typedoc --out docs src/index.ts
-
-# JSDoc
-npx jsdoc src/ -d docs/
-
-# API Extractor (monorepos)
-npx api-extractor run
-```
-
-### Python
-
-```bash
-# Sphinx
-sphinx-build -b html docs docs/_build
-
-# pdoc
-pdoc --output-dir docs src/
-
-# mkdocs
-mkdocs serve
-```
-
-### Go
-
-```bash
-# godoc
-godoc -http=:6060
-
-# swag (OpenAPI from comments)
-swag init -g cmd/server/main.go
-```
-
----
-
-## Workflow
-
-### 1. Identify what needs docs
-
-- New files/features → update relevant doc
-- Breaking change → update CHANGELOG
-- New public API → update API docs
-
-### 2. Generate/Update
-
-- Run doc generators
-- Update manual docs
-- Verify examples work
-
-### 3. Verify
-
-- Links work
-- Examples run
-- Build passes
-
-### 4. Commit
-
-```
-docs: update API documentation
-
-Generated via typedoc.
-Added: new /users endpoint
-Changed: authentication section
-```
-
----
-
-## Best Practices
-
-1. **Write docs in the code** - Docstrings, comments
-2. **Generate where possible** - Don't duplicate
-3. **Keep README minimal** - Link to detailed docs
-4. **Version with code** - Docs in same repo/PR
-5. **Test examples** - Ensure they run

package/skills/code-docs/references/api-docs.md

@@ -1,116 +0,0 @@
-# API Documentation Tools
-
-## TypeScript/JavaScript
-
-### TypeDoc
-
-```bash
-npm install --save-dev typedoc
-
-# Generate
-npx typedoc --out docs src/index.ts
-
-# Options
---entryPoints src/
---out docs/
---name "My Project"
---theme default
-```
-
-### JSDoc
-
-```bash
-npm install --save-dev jsdoc
-
-# Generate
-npx jsdoc src/ -d docs/
-
-# Config (jsdoc.json)
-{
-  "source": {
-    "includePattern": ".+\\.js(doc)?$"
-  },
-  "opts": {
-    "destination": "./docs/"
-  }
-}
-```
-
----
-
-## Python
-
-### Sphinx
-
-```bash
-pip install sphinx
-
-# Initialize
-sphinx-quickstart
-
-# Build
-make html
-```
-
-### pdoc
-
-```bash
-pip install pdoc
-
-# Generate
-pdoc --output-dir docs src/
-pdoc --logo logo.png src/  # With logo
-```
-
----
-
-## Go
-
-### godoc
-
-```bash
-# Install
-go install golang.org/x/tools/cmd/godoc@latest
-
-# Run locally
-godoc -http=:6060
-```
-
-### swag (OpenAPI)
-
-```bash
-go install github.com/swaggo/swag/cmd/swag@latest
-
-# Generate from annotations
-swag init -g cmd/server/main.go
-```
-
----
-
-## OpenAPI/Swagger
-
-### tools
-
-- swagger-cli validate
-- @apidevtools/swagger-cli
-- redoc CLI
-
-### Annotations Example
-
-```javascript
-/**
- * @openapi
- * /users:
- *   get:
- *     summary: List users
- *     responses:
- *       200:
- *         description: User list
- *         content:
- *           application/json:
- *             schema:
- *               type: array
- *               items:
- *                 $ref: '#/components/schemas/User'
- */
-```

package/skills/code-docs/references/changelog.md

@@ -1,64 +0,0 @@
-# Changelog Format
-
-## Keep a Changelog
-
-Follow: https://keepachangelog.com
-
-## Format
-
-```markdown
-# Changelog
-
-All notable changes to this project will be documented in this file.
-
-## [Unreleased]
-
-### Added
-- New feature
-
-### Changed
-- Changed behavior
-
-### Deprecated
-- Soon-to-be removed feature
-
-### Removed
-- Now removed feature
-
-### Fixed
-- Bug fix
-
-### Security
-- Security improvement
-```
-
-## Version Template
-
-```markdown
-## [1.0.0] - 2024-01-15
-
-### Added
-- Users can now authenticate via OAuth
-- New /api/users/:id endpoint
-
-### Changed
-- Authentication now uses JWT tokens
-
-### Fixed
-- Fixed race condition in user creation
-```
-
-## Rules
-
-1. One version per section
-2. Chronological order (newest first)
-3. Link to issues/pr
-4. Mention breaking changes
-5. Use imperative mood
-
-## Example Entry
-
-```markdown
-### Added
-- Add user profile endpoint (#123, @username)
-```

package/skills/code-docs/references/readme-structure.md

@@ -1,94 +0,0 @@
-# README Structure
-
-## Quick Template
-
-```markdown
-# Project Name
-
-One-sentence description.
-
-[![Build](https://img.shields.io/badge/build-passing-green)](link)
-[![Version](https://img.shields.io/npm/v/package.svg)](link)
-[![License](https://img.shields.io/badge/license-MIT-blue)](link)
-
-## Features
-
-- Feature 1
-- Feature 2
-- Feature 3
-
-## Quick Start
-
-```bash
-npm install package-name
-npm start
-```
-
-## Installation
-
-### Prerequisites
-
-- Node.js 18+
-- npm 9+
-
-### Steps
-
-1. Clone repo
-2. Install deps: npm install
-3. Configure: cp .env.example .env
-4. Run: npm run dev
-
-## Usage
-
-```javascript
-const pkg = require('package-name');
-
-pkg.doSomething();
-```
-
-## API
-
-See [API Documentation](docs/api.md).
-
-## Configuration
-
-| Env | Description | Default |
-|-----|-------------|---------|
-| PORT | Server port | 3000 |
-| DB_URL | Database connection | localhost |
-
-## Development
-
-```bash
-npm run dev    # Start dev server
-npm test       # Run tests
-npm run lint   # Lint
-```
-
-## Contributing
-
-1. Fork
-2. Branch: feature/my-feature
-3. Commit
-4. PR
-
-## License
-
-MIT
-```
-
-## Sections to Include
-
-| Section | Required | Description |
-|---------|----------|-------------|
-| Title + Badges | Yes | Project name, version, status |
-| Description | Yes | What it does |
-| Features | Yes | Key capabilities |
-| Quick Start | Yes | 3-5 commands |
-| Installation | No | Detailed setup |
-| Usage | No | Code examples |
-| API | No | For libraries |
-| Configuration | No | Env vars, settings |
-| Development | No | Dev commands |
-| Contributing | No | How to contribute |
-| License | Yes | Open source license |