@martinffx/atelier 1.0.2 → 1.2.0

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # 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)
+
+
+### Features
+
+* **skills:** add oracle-grillme socratic interrogation skill ([6ad5ce5](https://github.com/martinffx/atelier/commit/6ad5ce52428863b51fec83880ce8083bb80aa3a0))
+* **skills:** add oracle-grillme socratic interrogation skill ([fd21606](https://github.com/martinffx/atelier/commit/fd2160639b82ba335963bec3128d9c6a5b5801b6))
+* **skills:** add PR creation workflow to code-commit ([25bb826](https://github.com/martinffx/atelier/commit/25bb8264364cb1c5ee843baea0127eaba3935c78))
+
 ## [1.0.2](https://github.com/martinffx/atelier/compare/v1.0.1...v1.0.2) (2026-05-23)
 
 

package/README.md

@@ -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,13 +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-security` — Security audit and vulnerability detection
-- `code-perf` — Performance profiling and optimization
-- `code-git-worktrees` — Isolated git worktrees for feature work
-- `code-stacked-commit` — Manage stacked commits with Graphite
+- `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.0.2",
+  "version": "1.2.0",
   "description": "Personal development toolkit - spec-driven development, code quality, deep thinking, and ecosystem patterns",
   "type": "module",
   "bin": {

package/skills/{code-conventional-commit → code-commit}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: code-conventional-commit
+name: code-commit
 description: Generate and validate conventional commit messages following the conventionalcommits.org spec. Use whenever the user wants to commit code, mentions commit messages, git commit, or asks to create a commit. Triggers on "commit", "git commit", "conventional", or when reviewing commit message format.
 user-invocable: true
 ---
@@ -76,6 +76,21 @@ When user asks to validate or check a commit message:
 4. Check subject follows rules (lowercase, imperative, no period)
 5. Flag any issues found
 
+### 3. Create Pull Request
+
+When user wants to open a PR or after finishing commits on a feature branch:
+
+1. Verify on a feature branch (not main): `git branch --show-current`
+2. Check for project PR template: `ls .github/PULL_REQUEST_TEMPLATE.md`
+3. Push branch if needed: `git push -u origin <branch>`
+4. Create PR via `gh pr create`:
+   - Use `--fill` if commits are clean (auto-populates title/body)
+   - Use `--draft` for work-in-progress
+   - Use interactive mode if body needs custom content
+5. Show the PR URL to the user
+
+See [references/pr-workflow.md](references/pr-workflow.md) for full workflow details.
+
 ## Input Methods
 
 | Input | Action |

package/skills/code-commit/references/pr-workflow.md

@@ -0,0 +1,145 @@
+# Pull Request Workflow
+
+Creating GitHub pull requests via the `gh` CLI.
+
+## Prerequisites
+
+- `gh` CLI installed and authenticated: `gh auth status`
+- Remote `origin` points to GitHub: `git remote -v`
+- On a feature branch (not main): `git branch --show-current`
+
+## Check for Project Template
+
+Before creating a PR, check if the project has its own PR template:
+
+```bash
+# Check for PR template in .github/
+ls .github/PULL_REQUEST_TEMPLATE.md 2>/dev/null || echo "No project template found"
+```
+
+**If found:** Use it. The `gh pr create` command will automatically pick it up.
+
+**If not found:** Use the minimal template below.
+
+---
+
+## Create Pull Request
+
+### Option 1: Auto-fill from commits (recommended)
+
+```bash
+gh pr create --fill
+```
+
+This uses the commit messages as the PR title and body. Best when commits are clean and conventional.
+
+### Option 2: Interactive
+
+```bash
+gh pr create
+```
+
+Opens an editor with the template. Fill in title and body interactively.
+
+### Option 3: Inline (for simple PRs)
+
+```bash
+gh pr create --title "feat(auth): add JWT authentication" --body "Implements token-based auth with refresh support."
+```
+
+---
+
+## PR Title Format
+
+Follow conventional commit style for PR titles:
+
+```
+<type>(<scope>): <description>
+```
+
+Examples:
+- `feat(api): add user profile endpoint`
+- `fix(db): resolve connection pool leak`
+- `docs(readme): update installation instructions`
+
+---
+
+## PR Body Template (fallback if no project template)
+
+```markdown
+## Description
+<!-- What does this PR do? -->
+
+## Changes
+<!-- What changed? -->
+
+## Testing
+<!-- How was this tested? -->
+
+## Checklist
+- [ ] Tests pass
+- [ ] Commits follow conventional format
+- [ ] Documentation updated (if needed)
+```
+
+---
+
+## Linking Issues
+
+Add issue references in the PR body:
+
+```markdown
+Closes #123
+Fixes #456
+Relates to #789
+```
+
+This auto-closes linked issues when the PR merges.
+
+---
+
+## Draft PRs
+
+For work-in-progress PRs:
+
+```bash
+gh pr create --draft
+```
+
+Mark as ready later:
+
+```bash
+gh pr ready <pr-number>
+```
+
+---
+
+## Review Requests
+
+Request reviewers after creating the PR:
+
+```bash
+gh pr edit <pr-number> --add-reviewer username
+```
+
+Or add via the GitHub web UI.
+
+---
+
+## Verify PR Created
+
+```bash
+gh pr view --web  # Open in browser
+gh pr status      # Show PR status
+```
+
+---
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| PR from main branch | Switch to feature branch first |
+| No remote | `git remote add origin <url>` |
+| Unpushed commits | `git push -u origin <branch>` |
+| PR body is empty | Use `--fill` or write a description |

package/skills/code-debug/SKILL.md

@@ -1,262 +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]."
-
----
-
-### Step 2: Isolate
-
-Narrow down where the bug lives using binary search.
-
-**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?
-
-**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
-```
-
-**Output:** "The bug is in [specific file/function/component]."
+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 3: Form Hypothesis
+## Phase 1 — Build a feedback loop
 
-Make a testable guess about the root cause.
+**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.
 
-**Good hypothesis:**
-- Specific: "The user ID is undefined because..."
-- Testable: Can verify with a test or log
-- Grounded: Based on evidence, not guess
+Spend disproportionate effort here. **Be aggressive. Be creative. Refuse to
+give up.**
 
-**Questions to ask:**
-- Why does this happen?
-- What are the preconditions?
-- What's the actual vs expected behavior?
-- What changed recently?
+### Ways to construct one — try them in roughly this order
 
-**Output:** "I hypothesize that [root cause] because [evidence]."
+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.
 
-### Step 4: Fix
+### Iterate on the loop itself
 
-Implement the fix based on your hypothesis.
+Treat the loop as a product. Once you have _a_ loop, ask:
 
-**Rules:**
-- Make minimal changes
-- Don't refactor while fixing (separate concerns)
-- Write failing test first if possible
-- Consider edge cases
+- 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.)
 
-**Fix patterns:**
-- **Missing value** → Add null check or default
-- **Wrong value** → Correct the logic
-- **Exception** → Handle the error case
-- **Logic error** → Fix the condition
+A 30-second flaky loop is barely better than no loop. A 2-second deterministic
+loop is a debugging superpower.
 
-**Output:** "Fix applied: [brief description]."
+### 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.
 
-### Step 5: Verify
+### When you genuinely cannot build a loop
 
-Confirm the fix works and doesn't break anything.
+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.
 
-**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
+Do **not** proceed to hypothesise without a loop.
 
-**Output:** "Fix verified. Tests passing. Regression test added."
+**Do not proceed to Phase 2 until you have a loop you believe in.**
 
 ---
 
-## Debugging Techniques
+## Phase 2 — Reproduce
 
-### Print Debugging
+Run the loop. Watch the bug appear.
 
-Quick and dirty, but sometimes the fastest way.
+Confirm:
 
-**When to use:**
-- Quick checks in development
-- When debugger isn't available
-- Understanding flow in unfamiliar code
+- [ ] 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.
 
-**Best practices:**
-- Print at entry/exit of functions
-- Print variable values at key points
-- Remove print statements before committing
-- Consider structured logging instead
+**Do not proceed until you reproduce the bug.**
 
-### 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
+## Phase 5 — Fix + regression test
 
-### Null/Undefined Errors
+Write the regression test **before the fix** — but only if there is a
+**correct seam** for it.
 
-**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;
-```
+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.
 
-### Race Conditions
+**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.
 
-**Symptoms:** Intermittent failures, flaky tests
+If a correct seam exists:
 
-**Debug approach:**
-1. Identify async operations
-2. Find timing dependencies
-3. Add delays or force ordering
+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.
 
-**Fix patterns:**
-- Use async/await properly
-- Add proper synchronization
-- Consider immutable state
-
-### 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
+---
 
-**Fix patterns:**
-- Fix the condition
-- Correct the calculation
-- Update the state correctly
+## Phase 6 — Cleanup + post-mortem
 
-### Performance Issues
+Required before declaring done:
 
-**Symptoms:** Slow, memory leaks, timeouts
+- [ ] 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
 
-**Debug approach:**
-1. Measure first (don't guess)
-2. Identify hot paths
-3. Optimize the bottleneck
+**Then ask: what would have prevented this bug?**
 
-**See code-perf skill for detailed performance debugging.**
+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 dealing with performance issues → load code-perf
-- If security vulnerability suspected → load code-security
-- 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
@@ -265,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.