@martinffx/atelier 3.0.1 → 3.0.2

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

@@ -1,157 +1,61 @@
 # Debugging Techniques
 
-## Print Debugging
+## Println Debugging
 
-### When to Use
-- Quick checks in development
-- When debugger isn't available
-- Understanding flow in unfamiliar code
-- Minimal reproducible cases
+Start with temporary, labeled output or the project's structured logger to establish execution
+order and inspect the values relevant to the current hypothesis. Print only the fields needed,
+include a unique session tag, and avoid tight loops. Move to tracing, profiling, or other heavier
+instrumentation only when focused logs cannot establish the evidence.
 
-### Best Practices
+Do not print credentials, authorization data, session identifiers, personal data, private
+payloads, or environment values. Remove temporary output once the investigation is complete.
 
-**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))`
+## Further Instrumentation
 
-**Don't:**
-- Leave print statements in production code
-- Print sensitive data (passwords, tokens)
-- Over-print (noise obscures signal)
-- Print in tight loops (use breakpoints instead)
+Instrument the smallest useful boundary. Record event order, identifiers, state transitions, and
+timing rather than entire payloads. Use a unique session tag for temporary instrumentation and
+remove only the instrumentation introduced for that session.
 
-### Tagged Debug Logs
+Never record credentials, authorization data, session identifiers, personal data, private
+payloads, or environment values. Treat captures, traces, and dumps as sensitive artifacts.
 
-When instrumenting during a debugging session, tag every temporary log with a
-unique prefix so cleanup is trivial:
+## Bisection
 
-```javascript
-console.log('[DEBUG-a4f2] userId:', userId);
-console.log('[DEBUG-a4f2] payload:', payload);
-```
+Narrow the failing path by disabling coherent branches, reducing inputs, or comparing a known-good
+revision with a known-bad revision. Keep the system valid while narrowing; arbitrary code removal
+can change the behavior being investigated.
 
-Cleanup: `grep -r '\[DEBUG-' .` → delete all matches.
+Before revision bisection, preserve unrelated work and record the starting revision. Reset to the
+starting state after the investigation.
 
-Untagged logs survive; tagged logs die.
+## Non-Deterministic Failures
 
----
+Record the conditions of every attempt: input, environment, timing, concurrency, seed, and result.
+Vary one condition at a time. Use delays and load only to perturb scheduling, never as proof of the
+cause. Prefer deterministic scheduling, fault injection, or recorded traces when available.
 
-## Structured Logging
+## Performance Investigation
 
-Better than `console.log` for production:
+Establish a representative baseline before changing code. Use measurements, profiling, tracing, or
+query plans that fit the suspected bottleneck. Avoid high-volume logging on the hot path because it
+can alter timing.
 
-```javascript
-const logger = {
-  debug: (msg, meta) => console.debug(JSON.stringify({ level: 'debug', msg, ...meta })),
-  info: (msg, meta) => console.info(JSON.stringify({ level: 'info', msg, ...meta })),
-  warn: (msg, meta) => console.warn(JSON.stringify({ level: 'warn', msg, ...meta })),
-  error: (msg, meta) => console.error(JSON.stringify({ level: 'error', msg, ...meta })),
-};
-```
+Some analysis tools execute the operation they inspect. Confirm whether a command is read-only and
+whether it can create load, acquire locks, or repeat side effects before using it outside an
+isolated environment.
 
-### Console Methods
+## Production Safety
 
-| Method | Use |
-|--------|-----|
-| console.log | General output |
-| console.debug | Debug info |
-| console.info | Informational |
-| console.warn | Warnings |
-| console.error | Errors |
-| console.table | Arrays/objects in table format |
-| console.trace | Stack trace |
-| console.time/timeEnd | Timing |
+Default to development, staging, or an isolated replica. Before production instrumentation,
+replay, or load generation, obtain explicit authorization and define scope, rate limits, rollback,
+and a stop condition. Replay only idempotent or dry-run operations unless the user explicitly
+accepts the side effects.
 
----
+## Cleanup
 
-## Binary Search Debugging
+Before closing the investigation:
 
-### Code Binary Search
-
-Comment out half the code to find where the bug is.
-
-### Git Bisect
-
-For regression bugs:
-
-```bash
-git bisect start
-git bisect bad
-git bisect good v1.2.3
-# Run your test, mark good/bad
-git bisect reset
-```
-
----
-
-## Rubber Ducking
-
-### The Process
-
-1. Describe the problem in detail
-2. Explain expected behavior
-3. Explain actual behavior
-4. Walk through the code line by line
-
----
-
-## Logging Strategies
-
-### What to Log
-
-| Log This | Don't Log This |
-|----------|----------------|
-| Request/response with IDs | Full request bodies |
-| Key decisions in code | Every loop iteration |
-| Error details with context | Stack traces |
-| Performance timing | Large data dumps |
-| User actions | Sensitive data (PII, passwords) |
-
-### Context to Include
-
-```javascript
-logger.error('Request failed', {
-  endpoint: '/api/users',
-  method: 'POST',
-  statusCode: 500,
-  userId: user?.id,
-  requestId: req.headers['x-request-id'],
-  duration: Date.now() - startTime,
-  errorMessage: error.message
-});
-```
-
-### Log Levels
-
-| Level | When |
-|-------|------|
-| DEBUG | Detailed debugging info |
-| 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
+- Remove temporary instrumentation and throwaway harnesses.
+- Preserve only sanitized evidence needed to explain the conclusion.
+- Re-run the original verification signal.
+- Record the confirmed cause, fix, and prevention measure.

package/skills/oracle-domain-modelling/SKILL.md

@@ -41,13 +41,16 @@ If a `CONTEXT-MAP.md` exists at the root, the repo has multiple contexts. The ma
 │       └── docs/adr/
 ```
 
-Create files lazily — only when you have something to write. If no `CONTEXT.md` exists, create one when the first term is resolved. If no `docs/adr/` exists, create it when the first ADR is needed.
+Read `docs/agents/domain.md` when it exists to locate the configured domain documents. Create files
+lazily — only when you have something to write. If no `CONTEXT.md` exists, create one when the
+first term is resolved. If no `docs/adr/` exists, create it when the first ADR is needed.
 
 ## During the session
 
 ### Challenge against the glossary
 
-When the user uses a term that conflicts with the existing language in `CONTEXT.md`, call it out immediately:
+When the user uses a term that conflicts with the existing language in the relevant `CONTEXT.md`,
+call it out immediately. Resolve `CONTEXT-MAP.md` first when present:
 
 > "Your glossary defines 'cancellation' as X, but you seem to mean Y — which is it?"
 

package/skills/oracle-grill-me/SKILL.md

@@ -15,6 +15,9 @@ Ask the questions one at a time, waiting for feedback on each question before co
 
 If a *fact* can be found by exploring the environment (filesystem, tools, etc.), look it up rather than asking me. The *decisions*, though, are mine — put each one to me and wait for my answer.
 
-Do not act on it until I confirm we have reached a shared understanding.
+Do not implement the proposed plan or decision until I confirm we have reached a shared
+understanding. Update domain documentation as terminology and decisions are resolved; when this
+session is nested in spec-brainstorm, return changed assumptions to that workflow for any required
+design update.
 
 Run this session using the `oracle-domain-modelling` skill.

package/skills/spec-brainstorm/SKILL.md

@@ -154,7 +154,8 @@ Read the relevant codebase deeply. Not signatures — implementations, edge case
 handling, data flows. Trace callers and callees. Read tests to understand expected
 behaviour.
 
-Write findings directly into the spec as the foundation.
+Collect research findings for the spec as the foundation. Do not write `design.md` until the
+approved design sections are assembled in Step 4c.
 
 **Tell the human:** "I've written the research section of the spec. Ready for you to
 review before I continue with the design."
@@ -334,14 +335,13 @@ note them at handoff.
 
 **Tell the human:**
 
-> "Spec written to `docs/specs/<path>`. Every section was approved during our
-> conversation - review it if you'd like, or we can go straight to the
-> Spec-backed Plan. Ready for spec-plan?"
+> "Spec written to `docs/specs/<path>`. Please confirm this assembled document before we move to
+> the Spec-backed Plan."
 
-If the human requests changes — in conversation or by annotating the file —
-address every note, update the spec, and re-run the self-review. If a change
-alters the substance of an approved section, re-present that section for
-approval before continuing.
+If the human requests changes — in conversation or by annotating the file — address every note,
+update the spec, and re-run the self-review. If a change alters the substance of an approved
+section, re-present that section for approval before continuing. Resolve questions that affect
+scope, architecture, contracts, data, security, or task ordering before handoff.
 
 The next step is **spec-plan** in Spec-backed mode. Do not start planning without the
 human's go-ahead. Do not write code.

package/skills/spec-finish/SKILL.md

@@ -10,20 +10,27 @@ user-invocable: true
 
 # Spec Finish
 
-Post-implementation workflow: validate → review → stack commits → prepare PR.
+Post-implementation workflow: synchronize docs → validate → review → prepare PR.
 
 ## Prerequisites
 
 Before starting, verify:
 1. All Spec-backed Plan tasks are complete
-2. Working directory is clean (committed or staged)
+2. Working directory has no unresolved staged or unstaged changes
 3. Tests pass
 
 If not complete, go back to `spec-implement`.
 
 ---
 
-## Step 1: Validate
+## Step 1: Update Documentation
+
+Check whether README, API documentation, or changelog updates are needed. Make and commit any
+necessary documentation changes through **code-commit** before final validation.
+
+---
+
+## Step 2: Validate
 
 Run validation checks.
 
@@ -67,12 +74,13 @@ go build ./...
 
 ---
 
-## Step 2: Review
+## Step 3: Review
 
-Use the Skill tool to invoke code-review skill for comprehensive code review.
+Invoke the installed **code-review** skill through the harness's skill mechanism for one
+comprehensive review of the final change.
 
 ### What to Review
-- All changed files since feature branch
+- All changed files since the intended base branch's merge base
 - Test coverage
 - Documentation updates
 - No debug code left
@@ -83,37 +91,17 @@ Use the Skill tool to invoke code-review skill for comprehensive code review.
 
 ---
 
-## Step 3: Stack Commits
-
-### Workflow
-1. Review current commits: `git log --oneline`
-2. Ensure commits are organized logically
-3. Rebase if needed: `git rebase -i <base-branch>`
-4. Ensure each commit is clean and functional
-
-### Commit Guidelines
-- Each commit should pass tests
-- Use conventional commit format
-- Meaningful commit messages
-
----
-
-## Step 4: Update Documentation
-
-### Check for Updates
-- README changes needed?
-- API documentation updated?
-- Changelog updated?
+## Step 4: Prepare Commits
 
-### If documentation needed
-- Update relevant docs
-- Commit with docs
+Review current commits with `git log --oneline`. Use **code-commit** for any uncommitted work.
+Do not rewrite history by default. If a rebase would materially improve an unpublished stack,
+show the affected range and ask for separate approval before rebasing.
 
 ---
 
-## Step 5: Open the PR
+## Step 5: Prepare the PR
 
-Steps 1-4 (validate, review, stack commits, update docs) must all be complete
+Steps 1-4 (documentation, validation, review, commits) must all be complete
 before proceeding. **If code-review found blocking or scope-changing issues, stop and return
 to spec-implement to fix them. Do not proceed to Step 5b.**
 
@@ -142,7 +130,7 @@ template, generates the body from commits, and opens the PR via `gh` or `glab`.
 
 ### Handoff
 
-> "Implementation complete. [N] commits stacked. Opening PR now."
+> "Implementation complete. [N] commits are ready. PR package ready for approval."
 
 ---
 

package/skills/spec-implement/SKILL.md

@@ -23,7 +23,8 @@ Before starting, verify these exist:
 
 1. Approved `docs/specs/YYYY-MM-DD-<feature>/design.md`
 2. Approved `docs/specs/YYYY-MM-DD-<feature>/plan.json`
-3. Any tracker entries selected during planning are available
+3. Any tracker entries selected during planning are available, along with
+   `docs/agents/issue-tracker.md` when tracking is configured
 4. You are not on main/master without explicit user consent. Create a branch or use a git
    worktree first.
 
@@ -85,34 +86,19 @@ Default to batched if the human hasn't expressed a preference.
 
 Follow the approved plan exactly.
 
-For each task, find the next ready task:
+For each task, find the next unblocked task directly from `plan.json`. When tracker entries
+exist, use `docs/agents/issue-tracker.md` to keep their execution state in sync; tracker state
+never overrides the plan's dependency graph.
 
-**With beads (preferred):**
-```bash
-bd ready --label <feature> --json
-```
-
-**With harness todos:** Check the todo list for the next unblocked task, respecting
-`depends_on` from plan.json.
-
-**Without a tracker:** Read the next unblocked task directly from plan.json.
-
-When a tracker exists, mark it in progress:
-
-**With beads:**
-```bash
-bd update <task-id> --status in_progress
-```
-
-**With harness todos:**
-Update the todo status to in_progress.
+When a tracker exists, mark it in progress according to `docs/agents/issue-tracker.md`.
 
 ### For each task
 
 Read the task's **inputs** and **description** first.
 
-Write tests that cover the validation criteria before writing implementation.
-Invoke an installed language-specific testing skill when needed.
+For behavior-changing code tasks, write tests that cover the validation criteria before writing
+implementation. For documentation, configuration, migration, or verification-only tasks, use the
+task's stated validation instead. Invoke an installed language-specific testing skill when needed.
 
 ```
 1. Read task inputs and description
@@ -122,28 +108,22 @@ Invoke an installed language-specific testing skill when needed.
 5. Refactor if needed (tests stay green)
 ```
 
-Do NOT write implementation before tests. Do NOT skip "verify it fails." Do NOT write
-more code than needed to pass the test.
+For behavior-changing code, do NOT write implementation before tests. Do NOT skip "verify it
+fails." Do NOT write more code than needed to pass the test.
 
 Verify the task against its **validation** and acceptance criteria.
 
-### After each batch: Review and commit
+### After each batch: Validate and commit
 
-In Subagent Mode, use **code-subagents** for one combined batch review. In other modes,
-invoke **code-review** once for the batch. Resolve blocking findings and revalidate, then the
-coordinator commits the reviewed batch serially using **code-commit**.
+Run the task's focused validation and inspect the local diff for accidental or out-of-scope
+changes. Report deviations and unexpected findings. Use **code-commit** for any commit; plan
+approval does not bypass its approval gate. Comprehensive **code-review** happens in
+**spec-finish**.
 
 ### On completion
 
-When a tracker exists, mark the task done:
-
-**With beads:**
-```bash
-bd close <task-id> --reason "Implemented with tests"
-```
-
-**With harness todos:**
-Mark the task as completed.
+When a tracker exists, mark the task complete according to
+`docs/agents/issue-tracker.md`.
 
 ### Referencing existing code
 
@@ -231,8 +211,11 @@ If the design was wrong:
 ## When to Revisit Earlier Steps
 
 **Return to spec-plan when:**
-- Partner updates the plan based on your feedback
-- Tasks can't be completed as specified
+- A material change affects approved behavior, scope, architecture, public contracts, or major dependencies
+- Tasks cannot be completed without one of those material changes
+
+Minor deviations may be recorded inline and reflected in plan.json when useful. Report them in the
+next progress update.
 
 **Return to spec-brainstorm when:**
 - The fundamental approach needs rethinking
@@ -248,9 +231,8 @@ When all planned work is done, verify and present it.
 
 1. **Run full test suite** — all tests must pass, not just the new ones
 2. **Run type check / lint** — clean output, no new warnings
-3. **Invoke code-review** — full review of all changes
-4. **Verify completion** — close every tracker entry when tracking is used
-5. **Diff review** — review the full diff against main/master. Look for:
+3. **Verify completion** — close every tracker entry when tracking is used
+4. **Diff review** — review the full diff against the intended base branch. Look for:
    - Files that changed but shouldn't have
    - Debug code or temporary hacks left behind
    - Inconsistencies between what was planned and what was built
@@ -274,7 +256,7 @@ Present to the human:
 - Test suite: ✓ all passing
 - Type check: ✓ clean
 - Lint: ✓ clean
-- Code review: ✓ complete
+- Comprehensive code review: pending spec-finish
 
 ### Ready for review
 ```

package/skills/spec-plan/SKILL.md

@@ -36,7 +36,7 @@ template with confirmed, file-and-symbol-level details, including cross-file wir
 ordering constraints where they matter.
 
 Do not manufacture phases, task IDs, dependency graphs, acceptance matrices, `design.md`,
-`plan.json`, Beads issues, or harness todos. The conversation is the plan artifact.
+`plan.json`, tracker entries, or harness todos. The conversation is the plan artifact.
 
 **Tell the human:** "Inline Plan ready for review."
 
@@ -227,27 +227,21 @@ into plan.json.
 
 ### Task Tracking
 
-Create tracker entries when they add execution value. For multi-task or dependency-ordered
-work, **prefer beads**:
-```bash
-# Create epic and tasks with dependencies
-bd create "Feature: {name}" --label {feature} --type epic
-bd create "Task: {name}" --label {feature} --type task --epic {epic-id}
-bd dep add --type blocks {task-a} {task-b}  # task-a blocks task-b
-```
-
-If tracking is useful and beads is unavailable, use the harness's native todo system.
-Do not duplicate a simple plan.json into a tracker merely to satisfy the workflow.
+Read `docs/agents/issue-tracker.md` when it exists. Create tracker entries only when that
+document configures a tracker, mirroring is enabled, and tracking adds execution value. Do not
+choose or configure a tracker here. Do not duplicate a simple plan.json into a tracker merely to
+satisfy the workflow.
 
 ### What to do
 
 1. Convert the annotated plan draft into structured plan.json
 2. Each task maps to a unit with inputs, description, files, and validation
 3. Dependencies between tasks are captured in `depends_on` fields
-4. When execution benefits from task tracking, create tasks using beads or harness todos:
-   - Create an epic/feature container
-   - Add tasks per phase with clear descriptions
-   - Mark dependencies between tasks (beads: `bd dep add`, harness: manual ordering)
+4. When execution benefits from configured task tracking, create entries according to
+   `docs/agents/issue-tracker.md`:
+   - Create any configured feature container
+   - Add tasks with clear descriptions
+   - Mirror dependencies when the configured tracker supports them
 5. The plan.json is the source of truth for task details; the task tracker
 tracks execution state
 
@@ -264,7 +258,7 @@ After creating plan.json, verify:
 
 ## Handoff
 
-When plan.json is created, and any useful tracker entries have been created, the next
+When plan.json is created, and any useful configured tracker entries have been created, the next
 step is **spec-implement** in Spec-backed mode.
 
 Tell the human:
@@ -277,8 +271,10 @@ Tell the human:
 
 Do not start implementing. That's spec-implement's job.
 
-If implementation reveals missing tasks, update plan.json. If design is wrong,
-loop back to research. See **atelier-orchestrator** for iteration patterns.
+Minor implementation deviations may be recorded inline and reflected in plan.json when they do
+not change approved behavior, scope, architecture, public contracts, or major dependencies.
+Material changes return to spec-plan for renewed approval; design changes return to
+spec-brainstorm. See **atelier-orchestrator** for iteration patterns.
 
 ---