@skill-graph/cli 0.5.6

package/marketplace/skills/mental-models/SKILL.md

@@ -0,0 +1,126 @@
+---
+name: mental-models
+description: "Use when reasoning about how a system, user, or designer's internal model of behavior may diverge from reality — applies across UX, distributed systems, type systems, API design, and team collaboration. Covers the three-model frame (designer / system image / user), the two gulfs (execution and evaluation), analogy and metaphor as model-seeding, the five failure modes (transfer, overgeneralization, underspecification, drift, invariant blindness), the surface/operational/architectural/domain layering, and the discipline of validating a model against the system it claims to represent. Do NOT use for the visual representation of a model (use knowledge-modeling), for the formal-domain entities-attributes-relationships of conceptual modeling (use conceptual-modeling), for cognitive biases in decision-making (out of scope), or for empirically eliciting user models via research methods (use user-research)."
+license: MIT
+allowed-tools: Read Grep
+metadata:
+  metadata: "{\"schema_version\":6,\"version\":\"1.0.0\",\"type\":\"capability\",\"category\":\"foundations\",\"domain\":\"foundations/mental-models\",\"scope\":\"reference\",\"owner\":\"skill-graph-maintainer\",\"freshness\":\"2026-05-16\",\"drift_check\":\"{\\\\\\\"last_verified\\\\\\\":\\\\\\\"2026-05-16\\\\\\\"}\",\"eval_artifacts\":\"planned\",\"eval_state\":\"unverified\",\"routing_eval\":\"absent\",\"comprehension_state\":\"present\",\"stability\":\"experimental\",\"keywords\":\"[\\\\\\\"mental models\\\\\\\",\\\\\\\"mental model\\\\\\\",\\\\\\\"gulf of execution\\\\\\\",\\\\\\\"gulf of evaluation\\\\\\\",\\\\\\\"user model\\\\\\\",\\\\\\\"system model\\\\\\\",\\\\\\\"designer model\\\\\\\",\\\\\\\"conceptual model\\\\\\\",\\\\\\\"metaphor\\\\\\\",\\\\\\\"analogy\\\\\\\",\\\\\\\"model-system fit\\\\\\\",\\\\\\\"hidden invariant\\\\\\\",\\\\\\\"model drift\\\\\\\",\\\\\\\"shared understanding\\\\\\\",\\\\\\\"cognitive tool\\\\\\\",\\\\\\\"progressive disclosure\\\\\\\",\\\\\\\"race conditions in concurrent code\\\\\\\"]\",\"triggers\":\"[\\\\\\\"how do I think about\\\\\\\",\\\\\\\"users expect X but the system does Y\\\\\\\",\\\\\\\"this is confusing\\\\\\\",\\\\\\\"the user's model doesn't match\\\\\\\",\\\\\\\"why is this surprising\\\\\\\",\\\\\\\"what's the right metaphor\\\\\\\"]\",\"examples\":\"[\\\\\\\"users keep trying to drag a row to reorder but the table doesn't support drag — diagnose the model mismatch\\\\\\\",\\\\\\\"explain why race conditions across parallel tool calls are hard for developers to anticipate\\\\\\\",\\\\\\\"decide on the right metaphor for a feature that combines folders and tags\\\\\\\",\\\\\\\"the team disagrees on what 'workspace' means in the product — surface the divergent mental models\\\\\\\"]\",\"anti_examples\":\"[\\\\\\\"draw the boxes-and-arrows diagram of the system (use knowledge-modeling)\\\\\\\",\\\\\\\"name the React hook for managing form state (tactical implementation choice)\\\\\\\",\\\\\\\"write user-research interview questions (use user-research)\\\\\\\",\\\\\\\"teach a junior engineer about distributed-systems consistency models (use teaching-patterns)\\\\\\\"]\",\"relations\":\"{\\\\\\\"related\\\\\\\":[\\\\\\\"conceptual-modeling\\\\\\\",\\\\\\\"knowledge-modeling\\\\\\\",\\\\\\\"user-research\\\\\\\",\\\\\\\"semantics\\\\\\\"],\\\\\\\"boundary\\\\\\\":[{\\\\\\\"skill\\\\\\\":\\\\\\\"conceptual-modeling\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"conceptual-modeling owns the FORMAL representation of a domain (entities, attributes, relationships) for downstream use by schemas and APIs; this skill owns the COGNITIVE construct (how a mind represents the system), which is upstream of any formalism.\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"knowledge-modeling\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"knowledge-modeling owns the choice of representation paradigm (graphs, frames, rules, networks); this skill owns the discipline of reasoning about model-system fit before any paradigm is chosen.\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"user-research\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"user-research owns the methods for eliciting and validating user mental models empirically; this skill owns the framing of what a mental model is and how to reason about its accuracy.\\\\\\\"}],\\\\\\\"verify_with\\\\\\\":[\\\\\\\"user-research\\\\\\\"]}\",\"mental_model\":\"|\",\"purpose\":\"|\",\"boundary\":\"|\",\"analogy\":\"A mental model is to a system what a map is to a city — the map is not the territory, the map is useful precisely because it is smaller and selective, and a traveler navigating with the wrong map (a city map for a different city, an out-of-date map, a tourist map missing the metro) does not get lost because the map is 'wrong' but because the map's selectiveness does not match the route they need.\",\"misconception\":\"|\",\"concept\":\"{\\\\\\\"definition\\\\\\\":\\\\\\\"A mental model is the internal representation a person carries of how a system, domain, or set of relationships behaves — used to predict outcomes, plan actions, and interpret feedback. Mental models are constructed (from experience, instruction, analogy, and inference), private (each mind holds its own), and partial (no model captures the full complexity of its referent). They are the cognitive scaffolding that makes the world tractable; they are also the silent source of most surprise, frustration, and bug-shaped misunderstanding. The discipline of mental-models is the explicit study of how these representations are built, where they diverge from the systems they represent, and how to bring multiple models into alignment when collaborators, users, and systems are working from different ones.\\\\\\\",\\\\\\\"mental_model\\\\\\\":\\\\\\\"|\\\\\\\",\\\\\\\"purpose\\\\\\\":\\\\\\\"|\\\\\\\",\\\\\\\"boundary\\\\\\\":\\\\\\\"|\\\\\\\",\\\\\\\"taxonomy\\\\\\\":\\\\\\\"|\\\\\\\",\\\\\\\"analogy\\\\\\\":\\\\\\\"|\\\\\\\",\\\\\\\"misconception\\\\\\\":\\\\\\\"|\\\\\\\"}\",\"skill_graph_source_repo\":\"https://github.com/jacob-balslev/skill-graph\",\"skill_graph_protocol\":\"Skill Metadata Protocol v5\",\"skill_graph_project\":\"Skill Graph\",\"skill_graph_canonical_skill\":\"skills/mental-models/SKILL.md\"}"
+  skill_graph_source_repo: "https://github.com/jacob-balslev/skill-graph"
+  skill_graph_protocol: Skill Metadata Protocol v4
+  skill_graph_project: Skill Graph
+  skill_graph_canonical_skill: skills/mental-models/SKILL.md
+---
+
+# Mental Models
+
+## Coverage
+
+The cognitive discipline of building, evaluating, and aligning the internal representations that minds carry of systems, domains, and interactions. Covers the three-model frame (designer model / system image / user model), the two gulfs (execution and evaluation), the role of analogy and metaphor in seeding new models, the model failure modes (transfer, overgeneralization, underspecification, drift, invariant blindness), the difference between surface, operational, architectural, and domain models, the methods for surfacing and repairing mental models through interface and documentation, and the cross-domain application of mental-models reasoning to UX, distributed systems, type systems, API design, and team collaboration.
+
+## Philosophy
+
+Mental models are how minds make systems tractable. Every user, every developer, every stakeholder operates from a model — partial, private, learned. Most surprise, most "confusing UX," most "miscommunication," most "user error" is the trace of a model-system gap. The disciplined response is to ask which model differs from which referent, where, and which intervention closes the gap — not to ask whose fault the surprise was.
+
+The discipline holds three commitments. First: that the user, the developer, and the system are three distinct sources of truth, each with their own model, none of which is automatically right. Second: that the interface is the bridge through which the system's actual model can become visible enough to repair user models in flight. Third: that the right model for a role is the smallest model that supports successful action in that role — not the most complete model, not the most accurate model in some absolute sense, but the model that does the work and no more.
+
+For agents working in software systems, mental-models discipline is the layer that decides what model to operate from before deciding what code to write. An agent that imports a wrong metaphor — "git branches are tree branches," "React state is OOP state," "a webhook is a function call" — produces code that compiles but doesn't work. The discipline is to make the operating model explicit, to test its predictions against the system, and to surface the gap before it becomes a bug.
+
+## The Three-Model Frame
+
+Norman's foundational distinction. Every system involves three models that may or may not align.
+
+| Model | Held by | Built from | Failure mode when divergent |
+|---|---|---|---|
+| **Designer's model** | The builders | Intent, specs, internal docs | "I built it this way; why doesn't anyone get it?" — usually the system image fails to convey the designer's model |
+| **System image** | The interface itself | Visual design, behavior, copy, feedback | An accurate system that looks wrong, or an inaccurate system that looks reasonable — both confuse users |
+| **User's model** | Each user | Interface, prior experience, instruction | User takes actions that match their model but not the system; reports the system as buggy |
+
+The interface is the only channel by which the designer's model can reach the user. If the interface is opaque, inconsistent, or contradicts the system's actual behavior, the user constructs the best model they can from incomplete signals — and that model will be wrong in predictable ways.
+
+## The Two Gulfs
+
+Norman's framework for where model failure shows up.
+
+| Gulf | Question it asks | What widens it | What narrows it |
+|---|---|---|---|
+| **Gulf of execution** | "How do I do what I want to do?" | Hidden affordances, non-discoverable commands, jargon controls | Direct manipulation, obvious primary action, learned conventions matched correctly |
+| **Gulf of evaluation** | "What did the system actually do?" | Silent state changes, no feedback, ambiguous results | Immediate visible feedback, undo, state inspection, clear confirmations |
+
+A wide gulf of execution means the user can't find the right action. A wide gulf of evaluation means they can't tell whether their action succeeded. Both are bridged by surfacing the system's state in a form the user's model can read.
+
+## Model Failure Modes And Their Interventions
+
+| Failure mode | What it looks like | Intervention |
+|---|---|---|
+| **Transfer failure** | User applies a model from another system whose details don't fit ("I tried to drag this row to reorder, like every other table") | Surface the difference explicitly: tooltip, copy, signifier change. Or implement the expected behavior. |
+| **Overgeneralization** | A pattern that worked in one context applied beyond its scope ("I tried to click outside the dialog to dismiss; it was a modal that requires explicit choice") | Signal boundaries: visual cues, copy that names the constraint, behavioral signals |
+| **Underspecification** | The user has a model that's silent on the case they hit ("I assumed undo would work everywhere; this action wasn't undoable") | Progressive disclosure of the relevant constraint at the moment of relevance, not in advance |
+| **Drift** | A model that was once correct but no longer matches ("I learned this workflow last year; it has three new steps now") | Change communication: in-product release notes, prompts on first encounter with changed behavior, removal of stale documentation |
+| **Invariant blindness** | The system has a rule the user doesn't know about ("you can edit this except when another user has it locked, and the lock isn't visible") | Surface the invariant at the moment of relevance: lock indicator, error message that names the rule, preflight check |
+
+The right intervention depends on the right diagnosis. "Train the user harder" is almost never correct — the user's model came from somewhere, usually from the interface or precedent.
+
+## Metaphor As Model-Seeding
+
+A new mental model is most often constructed by analogy from an existing one. The chosen metaphor has long downstream effects.
+
+| Metaphor | What it seeds | What it costs |
+|---|---|---|
+| File ⟶ paper-in-folder | Discrete unit; in one place; can be moved | Implies physical containment that cloud-sync, multi-tag, and shared-link systems violate |
+| Email folder ⟶ filing cabinet | Mutually exclusive categories | Doesn't fit messages that belong in multiple buckets — tags model fits better |
+| Web page ⟶ printed document | Static, paginated, top-to-bottom | Doesn't fit dynamic, interactive, scrollable, infinite-content pages |
+| API call ⟶ function call | Synchronous, single-machine, return-immediately | Hides network failure, latency, retries, partial failure |
+| Thread ⟶ worker | Independent unit; pauseable | Doesn't surface the shared-memory failure modes that cause actual concurrency bugs |
+| Database transaction ⟶ all-or-nothing | Strong atomicity | Doesn't fit weaker isolation levels (Read Committed, etc.); see `transaction-isolation` |
+
+Choosing a metaphor commits the designer to surfacing the points where it breaks down. The metaphor is useful precisely because of its match; it is dangerous precisely because of its mismatches.
+
+## Applying The Discipline
+
+| Domain | Question to ask |
+|---|---|
+| **Designing a feature** | What's the user's model now? What model do we want them to have? What's the smallest interface change that bridges the two? |
+| **Naming a function or API** | What model does this name imply? Does the function actually behave that way? If not, rename or change behavior. |
+| **Writing an error message** | What model fragment caused this error? What model would prevent it? Can the error message implant the corrective model? |
+| **Onboarding a new user** | What metaphor will we seed? Will it still fit in 6 months when the user is fluent? |
+| **Resolving team disagreement** | Are we disagreeing about the system, or about each member's model of the system? Compare models before debating decisions. |
+| **Debugging a confusing codebase** | What model would make this code obvious? Why doesn't the code communicate that model? |
+| **Working with an agent on a codebase** | What model is the agent operating from? What would it predict about this code? Does the prediction match reality? |
+| **Architecting a distributed system** | What is the designer's model of consistency? What will the system actually exhibit? What's in the system image (logs, dashboards, error semantics) that lets operators build the right operational model? |
+
+## Verification
+
+After applying this skill, verify:
+- [ ] The system being designed, debugged, or discussed has the three models (designer / image / user) named separately, not conflated into a single "the system."
+- [ ] When the user surprises you, the diagnosis identifies which failure mode (transfer / overgeneralization / underspecification / drift / invariant blindness) is operating before any intervention is chosen.
+- [ ] When you choose a metaphor, you have explicitly listed at least one place it breaks down and how the interface will signal that breakdown.
+- [ ] When the team disagrees, you have asked whether the disagreement is about the system or about the models of the system, and you have surfaced the divergent models before adjudicating.
+- [ ] The model targeted for users is the smallest one that supports their role, not the most complete one that explains the implementation.
+- [ ] Interfaces, error messages, naming, and defaults are aligned (not all five elements implying contradictory models).
+- [ ] When you ship a model-shifting change, you have a mechanism to refresh user models (in-product notification, onboarding update, release note that explains the new model — not just the new behavior).
+- [ ] If you are an agent working in an unfamiliar codebase, you have named the model you are currently operating from and tested at least one prediction against the system before producing substantial code.
+
+## Do NOT Use When
+
+| Instead of this skill | Use | Why |
+|---|---|---|
+| Building a formal representation (entities, attributes, schemas) | `conceptual-modeling` | conceptual-modeling owns formal-domain representation; mental-models owns the cognitive layer above any formalism |
+| Choosing between graphs, frames, rules as a knowledge representation paradigm | `knowledge-modeling` | knowledge-modeling owns paradigm selection; mental-models is upstream of paradigm choice |
+| Empirically eliciting user mental models through research methods | `user-research` | user-research owns the elicitation methods; this skill owns the conceptual frame the methods serve |
+| Transferring a known mental model to another person | `teaching-patterns` | teaching-patterns owns the transmission discipline; this skill owns the construction discipline |
+| Reasoning about specific cognitive biases (anchoring, framing, recency) | (no direct skill — out of scope) | The cognitive-bias literature is its own discipline; this skill focuses on system-model representation rather than decision-making bias |
+| Choosing the React hook for a state-management decision | `state-management` + library docs | Tactical implementation choice; this skill is the upstream framing |
+| The drawing or notation of a model | diagramming tools / `knowledge-modeling` | The artifact is not the model; this skill applies to the cognitive structure, not its visual representation |
+
+## Key Sources
+
+- Norman, D. A. (1983). "Some Observations on Mental Models." In Gentner, D. & Stevens, A. L. (Eds.), *Mental Models* (pp. 7–14). Lawrence Erlbaum. The foundational designer's-model / system-image / user's-model framing, and the gulfs of execution and evaluation.
+- Norman, D. A. (2013). *The Design of Everyday Things* (Revised and Expanded Edition). Basic Books. The most accessible exposition of mental-models discipline applied to interface design; the three-model frame and the gulfs are presented in operational form.
+- Johnson-Laird, P. N. (1983). *Mental Models: Towards a Cognitive Science of Language, Inference, and Consciousness*. Harvard University Press. The canonical cognitive-science treatment of mental models as the internal structures over which reasoning operates.
+- Gentner, D., & Stevens, A. L. (Eds.). (1983). *Mental Models*. Lawrence Erlbaum. The collection that established the modern study of mental models across multiple domains (physics, calculators, navigation).
+- Senge, P. M. (1990). *The Fifth Discipline: The Art and Practice of the Learning Organization*. Doubleday. The application of mental-models discipline to organizational thinking, with emphasis on surfacing assumptions and challenging "the way things are."
+- Hutchins, E. (1995). *Cognition in the Wild*. MIT Press. The situated-cognition account: mental models are not purely internal but distributed across people, artifacts, and environments.
+- Kahneman, D. (2011). *Thinking, Fast and Slow*. Farrar, Straus and Giroux. Adjacent treatment of the System 1 / System 2 distinction, which intersects with how mental models are constructed (fast, pattern-matched) and challenged (slow, deliberate).
+- Carroll, J. M., & Mack, R. L. (1985). "Metaphor, computing systems, and active learning." *International Journal of Man-Machine Studies, 22*(1), 39–57. Foundational work on the role of metaphor in seeding mental models of computing systems, and on the production paradox (what users say vs what they do).
+- Korzybski, A. (1933). *Science and Sanity: An Introduction to Non-Aristotelian Systems and General Semantics*. Institute of General Semantics. The origin of "the map is not the territory" — the foundational distinction between representation and represented.
+- Clark, A. (2013). "Whatever next? Predictive brains, situated agents, and the future of cognitive science." *Behavioral and Brain Sciences, 36*(3), 181–204. The predictive-coding view, which reframes mental models as prior expectations the brain continuously tests against incoming evidence.

package/marketplace/skills/merge-queue/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: merge-queue
+description: "Use when serializing merges across multiple agent branches, resolving conflicts between agent outputs, or cleaning stale task branches. Covers atomic locking, idempotency checks, non-fast-forward handling, and worktree cleanup. Do NOT use for ordinary git operations outside an agent merge queue (use `version-control`)."
+license: MIT
+compatibility: "Markdown, Git, agent-skill runtimes"
+allowed-tools: Read Grep Bash
+metadata:
+  metadata: "{\"schema_version\":6,\"version\":\"1.0.0\",\"type\":\"workflow\",\"category\":\"engineering\",\"domain\":\"engineering/git\",\"scope\":\"portable\",\"owner\":\"skill-graph-maintainer\",\"freshness\":\"2026-04-01\",\"drift_check\":\"{\\\\\\\"last_verified\\\\\\\":\\\\\\\"2026-04-01\\\\\\\"}\",\"eval_artifacts\":\"planned\",\"eval_state\":\"unverified\",\"routing_eval\":\"absent\",\"stability\":\"experimental\",\"keywords\":\"[\\\\\\\"merge queue\\\\\\\",\\\\\\\"atomic lock\\\\\\\",\\\\\\\"idempotency\\\\\\\",\\\\\\\"no-ff merge\\\\\\\",\\\\\\\"worktree cleanup\\\\\\\",\\\\\\\"agent branch\\\\\\\",\\\\\\\"master merge\\\\\\\"]\",\"triggers\":\"[\\\\\\\"merge-queue\\\\\\\",\\\\\\\"agent-merge\\\\\\\"]\",\"relations\":\"{\\\\\\\"related\\\\\\\":[\\\\\\\"version-control\\\\\\\"],\\\\\\\"boundary\\\\\\\":[\\\\\\\"version-control\\\\\\\"]}\",\"portability\":\"{\\\\\\\"readiness\\\\\\\":\\\\\\\"scripted\\\\\\\",\\\\\\\"targets\\\\\\\":[\\\\\\\"skill-md\\\\\\\"]}\",\"lifecycle\":\"{\\\\\\\"stale_after_days\\\\\\\":90,\\\\\\\"review_cadence\\\\\\\":\\\\\\\"quarterly\\\\\\\"}\",\"skill_graph_source_repo\":\"https://github.com/jacob-balslev/skill-graph\",\"skill_graph_protocol\":\"Skill Metadata Protocol v5\",\"skill_graph_project\":\"Skill Graph\",\"skill_graph_canonical_skill\":\"skills/merge-queue/SKILL.md\"}"
+  skill_graph_source_repo: "https://github.com/jacob-balslev/skill-graph"
+  skill_graph_protocol: Skill Metadata Protocol v4
+  skill_graph_project: Skill Graph
+  skill_graph_canonical_skill: skills/merge-queue/SKILL.md
+---
+# Merge Queue (Serialized Commit Control)
+
+## Domain Context
+
+**What is this skill?** This skill manages the serialized merge queue for agent branches. Covers atomic locking, idempotency checks, non-fast-forward merges, and worktree cleanup. Use when merging multiple agent tasks to master, resolving merge conflicts between agents, or cleaning up stale task branches. Do NOT use for standard git operations (use version-control).
+
+## Coverage
+
+This skill manages the serialized merge queue for agent branches. The sections below contain the detailed rules, examples, and boundaries for using this skill correctly.
+
+## Key Files
+
+| File | Purpose |
+|---|---|
+| `scripts/agent/merge-queue.sh` | The primary CLI for managing the queue. |
+| `agent-orchestration/logs/events.jsonl` | Emits `merge_started` and `merge_completed` events. |
+## Workflow
+
+Use the ordered phases, checklists, and guardrails in the sections below as the canonical workflow for this skill. When multiple subsections describe steps, follow them in the order presented.
+
+## Queue Coverage
+
+Atomic merge locking (`merge.lock`), branch idempotency checks, `--no-ff` (non-fast-forward) merge policy, automated worktree and branch cleanup, and event emission.
+
+> The "Gatekeeper" for the master branch. Prevents agents from causing race conditions during the final commit phase.
+
+## Philosophy
+
+Merge queues exist to protect the main branch from concurrent merge failures. When multiple agents modify overlapping code simultaneously, merging them independently creates a false sense of safety — each agent's work may pass CI alone but break when combined. A merge queue serializes merges, ensuring every commit is tested against the current state of main plus all queued predecessors before pushing. The result is a main branch that is always in a known-good state, with clear task-level history preserved via non-fast-forward commits. This prevents both silent conflicts (where two agents unwittingly overwrite each other's work) and long debugging sessions trying to untangle which merge introduced a regression.
+
+## 1. The Merge Protocol
+
+To prevent merge conflicts and history pollution, all agents must submit their finished tasks to the merge queue.
+
+| Phase | Action | Tool |
+|---|---|---|
+| **Lock** | Acquire `merge.lock` | `scripts/agent/merge-queue.sh` (merge subcommand) |
+| **Verify** | Check branch state | Verify branch is up to date with master and passes tests. |
+| **Merge** | Non-FF Merge | Merge with `--no-ff` to preserve task history. |
+| **Cleanup** | Delete branch/worktree | Remove the git worktree and the remote task branch. |
+| **Release** | Release `merge.lock` | Allow the next agent in the queue to proceed. |
+
+## 2. Clever Features (Stolen from Merge Queue)
+
+- **Atomic Lock**: Only one agent can merge at a time, ensuring that master is always in a known good state.
+- **Idempotency**: If a merge fails halfway, the queue can be resumed without creating duplicate commits.
+- **Automated Cleanup**: Once a merge is successful, the `merge-queue.sh` automatically deletes the task-specific worktree (`/tmp/worktrees/SH-XXXX`) to save disk space.
+
+## 3. Managing the Queue
+
+- **Submit Merge**: `bash scripts/agent/merge-queue.sh merge --task SH-XXXX`
+- **Check Status**: `bash scripts/agent/merge-queue.sh status`
+- **Cleanup Manually**: `bash scripts/agent/merge-queue.sh cleanup --task SH-XXXX`
+
+## 4. Key Files
+
+| File | Purpose |
+|---|---|
+| `scripts/agent/merge-queue.sh` | The primary CLI for managing the queue. |
+| `.git/merge.lock` | (Virtual) The lock file preventing concurrent merges. |
+| `agent-orchestration/logs/events.jsonl` | Emits `merge_started` and `merge_completed` events. |
+
+## 5. Verification Protocol
+
+- **Lock Test**: Try to start two merges simultaneously; the second should wait or fail.
+- **Master Integrity**: Verify that master only contains `--no-ff` merge commits for agent tasks.
+- **Disk Space**: Verify that the `/tmp/worktrees/` directory is pruned after successful merges.
+
+
+## Do NOT Use When
+
+| Instead of this skill | Use | Why |
+|---|---|---|
+| (To be filled during next audit pass) | — | — |
+
+
+## Verification
+
+After applying this skill, verify:
+- [ ] Changes follow the patterns documented above
+- [ ] No regressions in affected functionality

package/marketplace/skills/methodology/SKILL.md

@@ -0,0 +1,317 @@
+---
+name: methodology
+description: "Use when planning multi-step implementations, designing quality gates, establishing verification protocols, or building agent checklists calibrated to known failure modes. Covers methodology/method/process distinctions, Cleanroom, PSP/TSP, hypothesis-driven development, DMAIC, checklist design, V&V frameworks, EDDOps, quality gates, and PDCA. Do NOT use for code-review verdicts (use `code-review`), behavior-preserving implementation work (use `refactor`), or test strategy (use `testing-strategy`)."
+license: MIT
+compatibility: "Markdown, Git, agent-skill runtimes"
+allowed-tools: Read Grep Bash
+metadata:
+  metadata: "{\"schema_version\":6,\"version\":\"1.0.0\",\"type\":\"capability\",\"category\":\"quality\",\"domain\":\"quality/method\",\"scope\":\"reference\",\"owner\":\"skill-graph-maintainer\",\"freshness\":\"2026-04-01\",\"drift_check\":\"{\\\\\\\"last_verified\\\\\\\":\\\\\\\"2026-04-01\\\\\\\"}\",\"eval_artifacts\":\"planned\",\"eval_state\":\"unverified\",\"routing_eval\":\"absent\",\"stability\":\"experimental\",\"keywords\":\"[\\\\\\\"methodology\\\\\\\",\\\\\\\"method\\\\\\\",\\\\\\\"process\\\\\\\",\\\\\\\"formal methods\\\\\\\",\\\\\\\"cleanroom\\\\\\\",\\\\\\\"PSP\\\\\\\",\\\\\\\"TSP\\\\\\\",\\\\\\\"hypothesis driven\\\\\\\",\\\\\\\"DMAIC\\\\\\\",\\\\\\\"PDCA\\\\\\\",\\\\\\\"Deming\\\\\\\",\\\\\\\"quality gates\\\\\\\",\\\\\\\"checklist manifesto\\\\\\\",\\\\\\\"verification validation\\\\\\\",\\\\\\\"DO-178C\\\\\\\",\\\\\\\"V&V\\\\\\\",\\\\\\\"EDDOps\\\\\\\",\\\\\\\"defect prevention\\\\\\\",\\\\\\\"shift left\\\\\\\",\\\\\\\"evidence based\\\\\\\"]\",\"triggers\":\"[\\\\\\\"methodology-skill\\\\\\\"]\",\"portability\":\"{\\\\\\\"readiness\\\\\\\":\\\\\\\"scripted\\\\\\\",\\\\\\\"targets\\\\\\\":[\\\\\\\"skill-md\\\\\\\"]}\",\"lifecycle\":\"{\\\\\\\"stale_after_days\\\\\\\":90,\\\\\\\"review_cadence\\\\\\\":\\\\\\\"quarterly\\\\\\\"}\",\"skill_graph_source_repo\":\"https://github.com/jacob-balslev/skill-graph\",\"skill_graph_protocol\":\"Skill Metadata Protocol v5\",\"skill_graph_project\":\"Skill Graph\",\"skill_graph_canonical_skill\":\"skills/methodology/SKILL.md\"}"
+  skill_graph_source_repo: "https://github.com/jacob-balslev/skill-graph"
+  skill_graph_protocol: Skill Metadata Protocol v4
+  skill_graph_project: Skill Graph
+  skill_graph_canonical_skill: skills/methodology/SKILL.md
+---
+# Methodology
+
+## Domain Context
+
+**What is this skill?** Provides the philosophical framework (methodology), specific techniques (methods), and ordered execution sequences (processes) that govern rigorous agent work. Covers the methodology-method-process stack, Cleanroom defect prevention, PSP/TSP measurement discipline, hypothesis-driven development, DMAIC quality management, aviation checklist design (Gawande), V&V frameworks (DO-178C/NASA), EDDOps for LLM agents, quality gates as hard stops, and the PDCA cycle for standardizing successes. Use when planning multi-step implementations, designing quality gates, establishing verification protocols, building agent checklists calibrated to known failure modes, or when an agent needs to understand WHY a process step exists (not just THAT it exists). Do NOT use for the specific behavioral rules of completeness and honesty (use methodical), quality definitions per artifact (use quality-doctrine), or generate-critique-revise loop mechanics (use self-review-pattern).
+
+## Coverage
+
+This skill covers the foundational frameworks that make rigorous agent work possible: the methodology-method-process three-layer stack (why these steps, not just which steps), Cleanroom defect prevention (quality built in, not inspected in), PSP/TSP measurement discipline (plan, review, post-mortem), hypothesis-driven development (define success criteria before the experiment), DMAIC/PDCA quality management (especially the skipped Control/Act phases), Gawande checklist design (calibrated to known failure modes, not generic), V&V frameworks from safety-critical industries (DO-178C bidirectional traceability, NASA verification standards), EDDOps for LLM agent evaluation (lifecycle coverage, slice-level validation, closed feedback loops), quality gates as hard stops (binary, blocking, measurable), and the 8 codifiable methodology patterns synthesized across all source disciplines.
+
+## Philosophy
+
+Agents default to executing process without methodology. They apply steps without understanding the principle that makes the steps necessary, which is exactly why they skip steps that feel low-value in the moment. A pilot who knows the B-17 crash story understands why the gust-lock check exists. A pilot who just has a checklist might skip it when running late.
+
+The academic distinction is load-bearing: **Methodology** is the philosophical framework — WHY you approach work a certain way. **Method** is a specific technique within the methodology. **Process** is the ordered sequence of steps executing a method. One process can contain multiple methods; one method can serve many processes. But without methodology, the agent has no basis for deciding when to apply extra rigor, when to challenge a process that seems wasteful, or when a shortcut is genuinely safe vs. when it compromises the underlying principle.
+
+This skill installs the WHY. The `methodical` skill installs the behavioral rules. Together they prevent both "knows the steps but skips them" (ineptitude) and "follows steps mechanically without understanding when they matter" (cargo culting).
+
+## Trio Boundaries
+
+methodology provides the *frameworks and principles* behind rigorous execution. It does NOT provide the specific behavioral rules for completeness and honesty — use `methodical` for that. It does NOT define what quality means per artifact type — use `quality-doctrine` for that. It does NOT provide the generate-critique-revise loop mechanics — use `self-review-pattern` for that.
+
+---
+
+## 1. The Three-Layer Stack
+
+| Layer | What It Is | Scope | Example |
+|---|---|---|---|
+| **Methodology** | The philosophical framework — WHY | Values, assumptions, epistemology | "Defect prevention is cheaper than defect removal" |
+| **Method** | A specific technique — HOW | Technique, approach, rules | "Run a type-check before committing" |
+| **Process** | An ordered sequence — WHEN | Steps, timing, handoffs | "1. Claim task → 2. Implement → 3. Verify → 4. Wrap" |
+
+**Operational rule:** Before executing any multi-step task, the agent must be able to articulate:
+1. What quality principle governs this work? (the methodology)
+2. What specific technique is being applied? (the method)
+3. In what order do the steps execute? (the process)
+
+If the agent cannot state #1, it is executing process without methodology — which is how skipped steps and silent shortcuts happen.
+
+---
+
+## 2. Cleanroom: Defect Prevention Over Removal
+
+Cleanroom software engineering (Harlan Mills, IBM) derives its name from semiconductor cleanrooms — environments designed to *prevent* contamination, not clean it up after.
+
+### The Three Pillars
+
+1. **Formal specification before implementation.** Behavior is specified before any code is written. Team reviews verify that design correctly implements specification — before implementation begins.
+2. **Incremental implementation with quality gates.** Each increment is measured against pre-established standards. Failure to pass a gate triggers return to design. Work cannot advance past a failed gate.
+3. **Statistical testing as experiment.** Testing is a designed experiment with defined coverage, not ad-hoc verification.
+
+### The Defect Cost Theorem
+
+| Phase Detected | Cost Multiplier |
+|---|---|
+| During design | 1x |
+| During code review | 6-10x |
+| During testing | 25-100x |
+| In production | 100x+ |
+
+Source: IBM Systems Sciences Institute, widely cited.
+
+**Translation to agent work:** Every pre-implementation check (acceptance criteria declared, existing patterns audited, assumptions externalized) prevents a post-task revision cycle. The PRE-TASK gate is not optional even when the task feels simple — simple tasks fail most often on defects that a pre-task check would have caught, because the agent doesn't bother checking assumptions it believes are obvious.
+
+---
+
+## 3. PSP/TSP: Measurement at the Individual Level
+
+The Personal Software Process (Watts Humphrey, SEI/CMU) applies capability maturity principles to individual engineers. TSP teams missed target schedules by an average of only 6%, versus a one-third failure rate for unaided projects.
+
+### PSP Phase Structure
+
+| Phase | What Happens | Agent Equivalent |
+|---|---|---|
+| **Planning** | Estimate using historical data. Never begin without a plan. | Pre-task declaration: scope, steps, risks |
+| **Design** | Specify the solution before implementing | Declare what tokens, states, components will be used |
+| **Design Review** | Personal review of design before coding — using a personal checklist | Self-check: "Have I seen this pattern before? What was the failure mode?" |
+| **Code** | Implement | Implement |
+| **Code Review** | Personal review before compile — same checklist discipline | Post-implementation self-check: all states present? all tokens correct? |
+| **Test** | Verify against planned acceptance criteria | Run verification against pre-declared criteria |
+| **Post-mortem** | Record actuals, calculate defect metrics, update historical data | Wrap findings: document what was discovered, update checklists |
+
+### The Defect Philosophy
+
+"Errors are usually predictable, so PSP developers can personalize their checklists to target their own common errors." PSP treats defect types as learnable patterns, not random events.
+
+**Agent application:** Agent checklists should include known agent failure modes:
+- Missing `aria-label` on icon-only buttons
+- Raw hex color instead of design token
+- Missing empty/error/loading state
+- Wrong heading level for component type
+- `tabular-nums` missing on financial amounts
+- Dark mode not verified
+- Mobile breakpoints not verified
+- Stale doc references after rename/delete
+
+---
+
+## 4. Hypothesis-Driven Development
+
+Every implementation decision is a hypothesis. The structure:
+
+```
+We believe [doing this]
+For [this system/component]
+Will achieve [this outcome]
+We will know we are right when [we observe this measurable signal]
+```
+
+**The critical discipline:** Define validation criteria BEFORE the experiment, not after observing results. This prevents confirmation bias — verifying against what you hoped to find rather than what is actually there.
+
+**Anti-pattern this prevents:** The "fix-by-guessing" loop — making changes until the symptom disappears without understanding the cause. This is treating symptoms rather than diagnosing disease.
+
+### Evidence-Based Decision Standard
+
+A decision is evidence-based when:
+1. The claim is stated explicitly before evidence is gathered
+2. Evidence is gathered by a method independent of the claim-holder's preference
+3. The evidence is compared against the pre-stated success criteria
+4. The decision and evidence are recorded for future reference
+
+"Looks good to me" is not evidence. "Should work" is not evidence. A screenshot, a test result, a command output — those are evidence.
+
+---
+
+## 5. DMAIC and Deming: Quality Management
+
+### DMAIC Applied to Agent Tasks
+
+| Phase | Agent Application |
+|---|---|
+| **Define** | State the problem, acceptance criteria, and scope. What does DONE look like? |
+| **Measure** | Gather baseline: current state, existing coverage, current defect rate |
+| **Analyze** | Root cause analysis: WHY does the defect exist? What structural pattern causes it? |
+| **Improve** | Implement the fix, targeting the root cause identified in Analyze |
+| **Control** | Regression test, checklist update, documentation — prevent recurrence |
+
+**The Control phase is what agents skip.** Fixing a bug without adding a regression test is a DMAIC failure. The defect will recur.
+
+### Deming's Most Transferable Points
+
+**Point 3 — Cease dependence on inspection.** Quality must be designed in, not inspected in at the end. Post-task review is a last resort, not the primary quality mechanism. Methodology that only activates when a reviewer asks is compliance theater.
+
+**Point 5 — Improve constantly every process.** Every completed task is a data point. Wrap findings that identify a recurring pattern must update the checklist or skill — not just document the finding.
+
+**Point 10 — Eliminate slogans and exhortations.** "Be more careful" and "write better code" are not instructions. Methodology replaces vague exhortations with specific, verifiable steps. "Check all interactive elements have visible focus states by tabbing through the page" is an instruction. "Make it accessible" is not.
+
+**Point 14 — Put everybody to work to accomplish the transformation.** Methodology is not a layer added by reviewers — it is internalized by every agent at every step.
+
+### PDCA Cycle
+
+```
+PLAN  → Define the task, declare acceptance criteria, identify risks
+DO    → Implement
+CHECK → Verify against acceptance criteria (not against memory of what you built)
+ACT   → If passing: standardize the pattern. If failing: return to PLAN.
+```
+
+**Critical insight:** The ACT phase applies to SUCCESSES as well as failures. Patterns that work should be standardized — added to checklists, documented in guides, encoded in skills. Wrap findings must document both what was fixed (failure learning) and what worked well (success learning).
+
+---
+
+## 6. Aviation Checklists (Gawande)
+
+### The Origin
+
+1935: Boeing B-17 prototype crashed on its maiden flight. The pilot forgot to disengage a gust lock. The plane was too complex for one person to manage from memory. The solution was not to hire better pilots. It was to create a checklist.
+
+### Two Categories of Failure
+
+1. **Ignorance** — we don't know what to do
+2. **Ineptitude** — we know what to do but fail to apply it under pressure
+
+Modern professional failures are almost entirely category 2. Agents skip `aria-label` not because they don't know it's required, but because attention is on the primary task when the icon button is written. Checklists prevent ineptitude failures by making minimum necessary steps explicit and resistant to skipping.
+
+### Checklist Design Principles
+
+- **Short.** Include only items where skipping causes serious consequences. Not every step.
+- **Calibrated.** Items should target the specific failure modes of the person/agent using the checklist. Generic checklists catch nothing.
+- **Two types:** Do-confirm (work from memory, then confirm) vs. Read-do (read each item, then do it). Read-do for novel/complex tasks. Do-confirm for familiar tasks.
+- **Point of use.** The checklist must be present at execution time, not in a document somewhere else.
+
+### Why "Being More Careful" Doesn't Work
+
+Agents skip steps because:
+- Attention is allocated to the primary task, not peripheral completeness requirements
+- Context window pressure creates implicit priority on the immediately visible goal
+- There is no external forcing function triggering a stop
+- "Close enough" is locally indistinguishable from "correct"
+
+Methodology — not effort — is the solution. Structured gates that must be explicitly cleared, in sequence, with evidence.
+
+---
+
+## 7. Verification and Validation (V&V)
+
+### The Distinction
+
+**Verification:** Are we building the product RIGHT? (Does implementation match specification?)
+**Validation:** Are we building the RIGHT product? (Does it meet the user's actual need?)
+
+A component can pass all token checks (verified) but solve the wrong UX problem (not validated). Both must pass.
+
+### DO-178C and NASA V&V
+
+**Bidirectional traceability.** Every requirement traced to code implementing it, test verifying it, and test results confirming it. No requirement is "done" without the complete trace.
+
+**V&V accounts for 70% of total development effort** in safety-critical industries. This is not waste — it is the work. Agents that treat verification as overhead are misallocating effort. Implementation is cheap; ensuring it is correct is expensive and unavoidable.
+
+**Independent verification.** The implementer's mental model contaminates their verification — they verify against what they INTENDED, not what they BUILT. Independent verification catches the gap.
+
+---
+
+## 8. EDDOps: Evaluation-Driven Development for LLM Agents
+
+### Six Quality Drivers (arXiv, 2024)
+
+| Driver | Requirement |
+|---|---|
+| **Lifecycle coverage** | Evaluation before deployment AND after AND continuously |
+| **Metric mix** | End-to-end scores AND step-level checks AND slice-aware checks |
+| **System-level anchor** | Evaluate full orchestration, not isolated model behavior |
+| **Adaptive evaluation** | Stable baselines + triggered probes when context changes |
+| **Closed feedback loops** | Findings must link to recorded changes — no untracked fixes |
+| **Human oversight** | Escalate ambiguous or high-impact cases to human judgment |
+
+### The Core Insight
+
+Evaluation is not a terminal checkpoint. It is a governing capability spanning the entire lifecycle. It is not "the last thing before shipping." It is the mechanism by which quality is maintained across every phase.
+
+**Slice-level validation:** After a fix, verify on the same failing case, not pooled aggregates. An improvement in overall scores that masks a regression in the failing case is a methodology failure.
+
+**Traceability mandate:** "All changes must be versioned and linked to originating evidence." For agents: every fix must be traceable to a specific finding. "Cleaned it up" is not a valid change record.
+
+---
+
+## 9. The 8 Codifiable Patterns
+
+These patterns appear across all source disciplines and translate directly into skill rules:
+
+| # | Pattern | Sources | Rule |
+|---|---|---|---|
+| 1 | **Declare Before Act** | Cleanroom + PSP + HDD + Gawande | Externalize intent before implementation; catches wrong assumptions |
+| 2 | **Quality Gates Are Hard Stops** | Cleanroom + DMAIC + DO-178C | Binary, blocking, measurable; "mostly passes" does not exist |
+| 3 | **Defect Prevention at Earliest Phase** | Cleanroom cost theorem + shift-left | Upstream checks cost 1x; downstream costs cascade to 100x |
+| 4 | **Evidence Replaces Belief** | HDD + PSP + V&V + EDDOps | Four components: criterion, test, observed result, comparison |
+| 5 | **Failure Modes Are Learnable** | PSP personalization + Gawande | Checklists calibrated to known failure modes, not generic |
+| 6 | **Methodology Must Be Internalized** | Deming Points 3, 14 | Quality designed in, not inspected in; compliance theater is not methodology |
+| 7 | **Independent Verification for High-Stakes** | V&V + EDDOps human oversight | Implementer's mental model contaminates self-verification |
+| 8 | **PDCA Standardizes Successes Too** | Deming PDCA ACT phase | Wrap findings encode what worked, not just what failed |
+
+---
+
+## 10. Anti-Patterns This Skill Prohibits
+
+| Anti-Pattern | Source Discipline | Why It Fails |
+|---|---|---|
+| "Looks good to me" as verification | PSP, V&V, HDD | Not a trace, not evidence, not reproducible |
+| Proceeding past a failing gate | Cleanroom, DO-178C | Downstream work compounds the upstream error |
+| Testing only the happy path | PSP, Cleanroom, DO-178C | Error states are where failures concentrate in production |
+| Fixing symptoms without root cause | DMAIC Analyze, HDD | Defect will recur under slightly different conditions |
+| Self-certifying without structured evidence | V&V independence, EDDOps | Mental model contamination |
+| Skipping pre-task "because it's simple" | PSP planning, Gawande | Simple tasks fail on overlooked assumptions MORE often |
+| Only learning from failures, not successes | PDCA ACT phase, PSP post-mortem | Success patterns are lost; only error avoidance is encoded |
+| Treating verification as overhead | V&V (70% of effort), DMAIC Control | Verification IS the work, not an addition to it |
+| Vague completion criteria | DMAIC Define, HDD, DO-178C | Unmeasurable criteria cannot be verified |
+
+---
+
+## Verification
+
+After applying this skill, verify:
+- [ ] Agent can articulate the methodology (WHY) behind each process step
+- [ ] Quality gates are binary pass/fail with evidence, not "mostly okay"
+- [ ] Pre-task declaration exists before implementation began
+- [ ] Post-task verification uses evidence, not belief
+- [ ] Checklists are calibrated to known agent failure modes
+- [ ] PDCA ACT phase captures successes, not just failures
+- [ ] Changes are traceable to originating findings (EDDOps traceability)
+
+## Do NOT Use When
+
+| Instead of this skill | Use | Why |
+|---|---|---|
+| Enforcing completeness and honesty rules | `methodical` | methodical has the 10 rules and anti-pattern catalog |
+| Defining what "better" means per artifact | `quality-doctrine` | quality-doctrine owns quality definitions |
+| Implementing generate-critique-revise loops | `self-review-pattern` | self-review-pattern owns the loop mechanics |
+| Sequencing task phases | `task-execution` | task-execution owns the workflow |
+| Designing agent governance policies | `agent-governance` | agent-governance owns policy and authority boundaries |
+
+## Key Sources
+
+- Mills, H. (1987). Cleanroom Software Engineering. IEEE Software.
+- Humphrey, W. (1995). A Discipline for Software Engineering (PSP). Addison-Wesley.
+- Humphrey, W. (2000). Introduction to the Team Software Process. SEI/CMU.
+- Gawande, A. (2009). The Checklist Manifesto. Metropolitan Books.
+- Boyd, J. (1976). OODA Loop. USAF.
+- Deming, W.E. (1986). Out of the Crisis. MIT Press.
+- DO-178C. Software Considerations in Airborne Systems and Equipment Certification.
+- IEEE 1012. Standard for System, Software, and Hardware Verification and Validation.
+- NASA (2014). Verification and Validation. Technical Reports Server.
+- EDDOps (2024). Evaluation-Driven Development of LLM Agents. arXiv:2411.13768.
+- Barry O'Reilly. Hypothesis-Driven Development.
+- Thoughtworks. How to Implement Hypothesis-Driven Development.