@martinffx/atelier 1.1.0 → 1.2.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## [1.2.0](https://github.com/martinffx/atelier/compare/v1.1.0...v1.2.0) (2026-05-23)
+
+
+### Features
+
+* **code-debug:** upgrade to six-phase diagnose workflow ([62dec10](https://github.com/martinffx/atelier/commit/62dec1045555947462a447f4579e83b0dee63d17))
+* **code-debug:** upgrade to six-phase diagnose workflow ([8df277d](https://github.com/martinffx/atelier/commit/8df277d425ca16dfa63a8bf1949003e3e6aaf87c))
+* **code-handoff:** add code-handoff skill ([5ab6f5f](https://github.com/martinffx/atelier/commit/5ab6f5f5d890b024718e3b69103b23c3eb1205ef))
+* **oracle-architect:** add vocabulary, evaluation heuristics, and interface design reference ([7c528d3](https://github.com/martinffx/atelier/commit/7c528d308ebc98929cfc6be17e8d5c7444b36607))
+* **oracle-architect:** add vocabulary, evaluation heuristics, and interface design reference ([63ee753](https://github.com/martinffx/atelier/commit/63ee75380c4d4be92708539173534566f2033dea))
+* **oracle-security:** add security architecture and threat modeling skill ([8fcbd87](https://github.com/martinffx/atelier/commit/8fcbd87943bcb23d51480ed9e9bd702f19817096))
+* **oracle-security:** add security architecture and threat modeling skill ([69b6fdc](https://github.com/martinffx/atelier/commit/69b6fdcdf1f2b7732fb339cbf1d64c1fb7252eb7))
+* **skills:** add code-handoff skill ([012f467](https://github.com/martinffx/atelier/commit/012f4676d48c7f6799361ca6bdfef12f33a8849e))
+* **skills:** add oracle-doubt skill ([adf118b](https://github.com/martinffx/atelier/commit/adf118be197da43195c9ddd052b53f8c714405b5))
+* **skills:** add oracle-doubt skill for adversarial review ([447673e](https://github.com/martinffx/atelier/commit/447673eb7904e4d28306360f64329f7874db5b2b))
+
 ## [1.1.0](https://github.com/martinffx/atelier/compare/v1.0.2...v1.1.0) (2026-05-23)
 
 

package/README.md

@@ -29,7 +29,7 @@ That's it. Your project is now configured for spec-driven development.
 
 Atelier sets up three things in your project:
 
-### 1. Skills (30 available)
+### 1. Skills (34 available)
 
 Specialized knowledge modules that auto-invoke based on context. Install them via the CLI (`--all` flag) or separately:
 
@@ -160,6 +160,9 @@ Analytical skills that provide patterns, principles, and deep reasoning. These a
 
 - `oracle-architect` — DDD, hexagonal architecture, component design
 - `oracle-challenge` — Challenge assumptions, validate decisions
+- `oracle-doubt` — Adversarial review of non-trivial decisions
+- `oracle-grillme` — Socratic interrogation of plans against domain model
+- `oracle-security` — Security architecture and threat modeling
 - `oracle-testing` — Stub-driven TDD, layer boundary testing
 - `oracle-thinkdeep` — Extended sequential reasoning for complex problems
 
@@ -191,9 +194,11 @@ Technology-specific patterns and best practices. These are like having a senior
 
 Task-specific tools you invoke when you need them.
 
-- `code-review` — Multi-agent code review with specialized reviewers
+- `code-commit` — Generate and validate conventional commits
 - `code-debug` — Systematic debugging workflow
 - `code-docs` — README, API docs, changelog generation
+- `code-handoff` — Compact conversation into handoff document
+- `code-review` — Multi-agent code review with specialized reviewers
 - `code-subagents` — Dispatch patterns for parallel implementation
 
 Skills are auto-invoked based on their description when you work with relevant technologies. No commands needed—just install and AI agents will use them when appropriate.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@martinffx/atelier",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Personal development toolkit - spec-driven development, code quality, deep thinking, and ecosystem patterns",
   "type": "module",
   "bin": {

package/skills/code-debug/SKILL.md

@@ -1,258 +1,190 @@
 ---
 name: code-debug
 description: >
-  Systematic debugging workflow and techniques. Use when something is broken, not working as
-  expected, or throwing errors. Covers reproduction, isolation, hypothesis formation, fix
-  implementation, and verification. Also triggers on "why does X fail", "debug this", "this
-  is broken", or when encountering errors or unexpected behavior.
+  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
 
-Systematic debugging workflow to find and fix bugs efficiently. Never guess — always
-narrow down the problem through systematic elimination.
+A discipline for hard bugs. Skip phases only when explicitly justified.
 
-## The Debugging Mindset
-
-| Bad | Good |
-|-----|------|
-| "I think it's..." | "Let me verify..." |
-| Changing random things | Binary search narrowing |
-| Hoping it'll work | Verifying each hypothesis |
-| Moving on after it works | Adding regression test |
-
-## The Five-Step Workflow
-
-### Step 1: Reproduce
-
-Create the smallest possible reproduction case.
-
-**Questions to answer:**
-- What exactly triggers the bug?
-- Can I make it happen on demand?
-- What's the minimal input that causes it?
-
-**Techniques:**
-- Extract exact steps from bug report
-- Remove unrelated factors
-- Create a minimal test case
-
-**Output:** "I can reproduce the bug by [exact steps]."
+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.
 
 ---
 
-### Step 2: Isolate
+## Phase 1 — Build a feedback loop
 
-Narrow down where the bug lives using binary search.
+**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.
 
-**Binary search strategies:**
-- Comment out half the code → does it still fail?
-- Isolate by layer: is it the UI, service, or data layer?
-- Isolate by file: which file contains the bug?
-- Isolate by function: which function causes the issue?
+Spend disproportionate effort here. **Be aggressive. Be creative. Refuse to
+give up.**
 
-**Git bisect** (for regression bugs):
-```bash
-git bisect start
-git bisect bad  # current commit is broken
-git bisect good <last-working-commit>
-# Run tests, mark good/bad
-git bisect reset  # done
-```
+### Ways to construct one — try them in roughly this order
 
-**Output:** "The bug is in [specific file/function/component]."
+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.
 
----
-
-### Step 3: Form Hypothesis
+Build the right feedback loop, and the bug is 90% fixed.
 
-Make a testable guess about the root cause.
+### Iterate on the loop itself
 
-**Good hypothesis:**
-- Specific: "The user ID is undefined because..."
-- Testable: Can verify with a test or log
-- Grounded: Based on evidence, not guess
+Treat the loop as a product. Once you have _a_ loop, ask:
 
-**Questions to ask:**
-- Why does this happen?
-- What are the preconditions?
-- What's the actual vs expected behavior?
-- What changed recently?
+- 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.)
 
-**Output:** "I hypothesize that [root cause] because [evidence]."
+A 30-second flaky loop is barely better than no loop. A 2-second deterministic
+loop is a debugging superpower.
 
----
+### Non-deterministic bugs
 
-### Step 4: Fix
+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.
 
-Implement the fix based on your hypothesis.
+### When you genuinely cannot build a loop
 
-**Rules:**
-- Make minimal changes
-- Don't refactor while fixing (separate concerns)
-- Write failing test first if possible
-- Consider edge cases
+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.
 
-**Fix patterns:**
-- **Missing value** → Add null check or default
-- **Wrong value** → Correct the logic
-- **Exception** → Handle the error case
-- **Logic error** → Fix the condition
+Do **not** proceed to hypothesise without a loop.
 
-**Output:** "Fix applied: [brief description]."
+**Do not proceed to Phase 2 until you have a loop you believe in.**
 
 ---
 
-### Step 5: Verify
-
-Confirm the fix works and doesn't break anything.
+## Phase 2 — Reproduce
 
-**Verification steps:**
-1. Run the reproduction case → should pass now
-2. Run related tests → should pass
-3. Run full test suite → should pass
-4. Add regression test → prevents future breakage
-
-**Output:** "Fix verified. Tests passing. Regression test added."
-
----
+Run the loop. Watch the bug appear.
 
-## Debugging Techniques
+Confirm:
 
-### Print Debugging
+- [ ] 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.
 
-Quick and dirty, but sometimes the fastest way.
+**Do not proceed until you reproduce the bug.**
 
-**When to use:**
-- Quick checks in development
-- When debugger isn't available
-- Understanding flow in unfamiliar code
-
-**Best practices:**
-- Print at entry/exit of functions
-- Print variable values at key points
-- Remove print statements before committing
-- Consider structured logging instead
-
-### Debugger
+---
 
-More powerful than print debugging.
+## Phase 3 — Hypothesise
 
-**When to use:**
-- Complex state to inspect
-- Stepping through logic
-- Evaluating expressions in context
+Generate **3–5 ranked hypotheses** before testing any of them. Single-hypothesis
+generation anchors on the first plausible idea.
 
-**See references/language-tools.md for language-specific debugger commands.**
+Each hypothesis must be **falsifiable**: state the prediction it makes.
 
-### Logging
+> Format: "If `<X>` is the cause, then `<changing Y>` will make the bug disappear / `<changing Z>` will make it worse."
 
-Better than print for production issues.
+If you cannot state the prediction, the hypothesis is a vibe — discard or sharpen it.
 
-**Strategies:**
-- Add context: request ID, user ID, correlation IDs
-- Log at appropriate levels: DEBUG, INFO, WARN, ERROR
-- Don't log sensitive data
-- Structured logging (JSON) for easier parsing
+**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.
 
-**See references/techniques.md for logging patterns.**
+---
 
-### Binary Search
+## Phase 4 — Instrument
 
-Halving the search space.
+Each probe must map to a specific prediction from Phase 3. **Change one variable
+at a time.**
 
-**Strategies:**
-- Comment out code blocks
-- Test with half the data
-- Compare working vs broken configurations
-- Git bisect for regressions
+Tool preference:
 
-### Rubber Ducking
+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".
 
-Explain the problem out loud (or to a rubber duck).
+**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.
 
-**Process:**
-1. Describe the problem in detail
-2. Explain what you expect to happen
-3. Explain what's actually happening
-4. Often the solution becomes clear mid-explanation
+**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.
 
 ---
 
-## Common Bug Patterns
-
-### Null/Undefined Errors
-
-**Symptoms:** Cannot read property X of undefined
-
-**Debug approach:**
-1. Find where the value becomes undefined
-2. Trace back where it should come from
-3. Add guard or fix source
+## Phase 5 — Fix + regression test
 
-**Fix patterns:**
-```javascript
-// Before
-const name = user.profile.name;
+Write the regression test **before the fix** — but only if there is a
+**correct seam** for it.
 
-// After
-const name = user?.profile?.name ?? 'Unknown';
-// or
-if (!user?.profile) return;
-const name = user.profile.name;
-```
-
-### Race Conditions
+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.
 
-**Symptoms:** Intermittent failures, flaky tests
+**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.
 
-**Debug approach:**
-1. Identify async operations
-2. Find timing dependencies
-3. Add delays or force ordering
+If a correct seam exists:
 
-**Fix patterns:**
-- Use async/await properly
-- Add proper synchronization
-- Consider immutable state
+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.
 
-### Logic Errors
-
-**Symptoms:** Wrong output, wrong behavior
+---
 
-**Debug approach:**
-1. Trace through the logic manually
-2. Compare expected vs actual at each step
-3. Find the first step that diverges
+## Phase 6 — Cleanup + post-mortem
 
-**Fix patterns:**
-- Fix the condition
-- Correct the calculation
-- Update the state correctly
+Required before declaring done:
 
-### Performance Issues
+- [ ] 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
 
-**Symptoms:** Slow, memory leaks, timeouts
+**Then ask: what would have prevented this bug?**
 
-**Debug approach:**
-1. Measure first (don't guess)
-2. Identify hot paths
-3. Optimize the bottleneck
+If the answer involves architectural change (no good test seam, tangled callers,
+hidden coupling) flag this as a codebase health finding for the team.
 
 ---
 
-## Skill Loading
+## References
 
-Check available skills for additional debugging support:
-
-- If debugging tests → load oracle-testing
-
----
+- **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, summarize:
+After each debugging session, summarise:
 
 ```
 ## Debug Summary
@@ -261,7 +193,7 @@ After each debugging session, summarize:
 **Root Cause:** [What actually was wrong]
 **Fix:** [How you fixed it]
 **Verification:** [Test results]
-**Prevention:** [Regression test added?]
+**Prevention:** [Regression test added? Architectural finding?]
 ```
 
 This helps future-you understand what happened.

package/skills/code-debug/references/bug-patterns.md

@@ -0,0 +1,71 @@
+# Common Bug Patterns
+
+Quick reference for recognising and fixing recurring bug categories.
+
+---
+
+## Null/Undefined Errors
+
+**Symptoms:** Cannot read property X of undefined
+
+**Debug approach:**
+1. Find where the value becomes undefined
+2. Trace back where it should come from
+3. Add guard or fix source
+
+**Fix patterns:**
+```javascript
+// Before
+const name = user.profile.name;
+
+// After
+const name = user?.profile?.name ?? 'Unknown';
+// or
+if (!user?.profile) return;
+const name = user.profile.name;
+```
+
+---
+
+## Race Conditions
+
+**Symptoms:** Intermittent failures, flaky tests
+
+**Debug approach:**
+1. Identify async operations
+2. Find timing dependencies
+3. Add delays or force ordering to confirm
+
+**Fix patterns:**
+- Use async/await properly
+- Add proper synchronization
+- Consider immutable state
+
+---
+
+## Logic Errors
+
+**Symptoms:** Wrong output, wrong behaviour
+
+**Debug approach:**
+1. Trace through the logic manually
+2. Compare expected vs actual at each step
+3. Find the first step that diverges
+
+**Fix patterns:**
+- Fix the condition
+- Correct the calculation
+- Update the state correctly
+
+---
+
+## Performance Issues
+
+**Symptoms:** Slow, memory leaks, timeouts
+
+**Debug approach:**
+1. Measure first (don't guess)
+2. Identify hot paths
+3. Optimize the bottleneck
+
+**See also:** Phase 4 "Perf branch" in SKILL.md for the disciplined approach.

package/skills/code-debug/references/techniques.md

@@ -13,8 +13,8 @@
 **Do:**
 - Print at function entry/exit to trace execution
 - Print variable values at key decision points
-- Use descriptive labels: console.log('userId:', userId)
-- Print full objects for inspection: console.log(JSON.stringify(data, null, 2))
+- Use descriptive labels: `console.log('userId:', userId)`
+- Print full objects for inspection: `console.log(JSON.stringify(data, null, 2))`
 
 **Don't:**
 - Leave print statements in production code
@@ -22,9 +22,25 @@
 - Over-print (noise obscures signal)
 - Print in tight loops (use breakpoints instead)
 
-### Structured Logging
+### Tagged Debug Logs
 
-Better than console.log for production:
+When instrumenting during a debugging session, tag every temporary log with a
+unique prefix so cleanup is trivial:
+
+```javascript
+console.log('[DEBUG-a4f2] userId:', userId);
+console.log('[DEBUG-a4f2] payload:', payload);
+```
+
+Cleanup: `grep -r '\[DEBUG-' .` → delete all matches.
+
+Untagged logs survive; tagged logs die.
+
+---
+
+## Structured Logging
+
+Better than `console.log` for production:
 
 ```javascript
 const logger = {
@@ -115,3 +131,27 @@ logger.error('Request failed', {
 | INFO | Normal operation events |
 | WARN | Something unexpected, but handled |
 | ERROR | Operation failed |
+
+---
+
+## Performance Regression Techniques
+
+### The Perf Branch
+
+For performance regressions, logs are usually wrong. Instead:
+
+1. **Establish a baseline measurement** using one of:
+   - Timing harness around the suspect code path
+   - `performance.now()` in browser / `process.hrtime()` in Node
+   - CPU profiler (Chrome DevTools, `node --prof`, py-spy, etc.)
+   - Database query planner (`EXPLAIN ANALYZE`)
+
+2. **Bisect** — narrow down which commit / change introduced the regression.
+
+3. **Measure first, fix second.** Do not optimise without data.
+
+### Hot Path Identification
+
+- Profile before guessing
+- Look for O(n²) algorithms, unnecessary renders, blocking operations
+- Check for N+1 queries, unbounded caches, recursive without memoisation

package/skills/code-handoff/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: code-handoff
+description: Compact the current conversation into a handoff document for another agent to pick up.
+argument-hint: "What will the next session be used for?"
+user-invocable: true
+---
+
+Write a handoff document summarising the current conversation so a fresh agent can continue the work. Save to the temporary directory of the user's OS - not the current workspace.
+
+Include a "suggested skills" section in the document, which suggests skills that the agent should invoke.
+
+Do not duplicate content already captured in other artifacts (PRDs, plans, ADRs, issues, commits, diffs). Reference them by path or URL instead.
+
+Redact any sensitive information, such as API keys, passwords, or personally identifiable information.
+
+If the user passed arguments, treat them as a description of what the next session will focus on and tailor the doc accordingly.