sliekens/engineering-workflow

Analyze a code path, system, workflow, or architecture to separate inherent complexity imposed by requirements and external constraints from accidental complexity introduced by the current implementation, then define the invariants a simplification must preserve. Use when the user asks what complexity is necessary or unavoidable, asks for inherent vs. accidental complexity, says a pipeline or subsystem feels too complex, wants to understand why something cannot be simpler, or wants a complexity map before refactoring. Also use before a technical-debt audit when unavoidable constraints and removable implementation complexity are mixed together. Do not use for exploring competing greenfield designs (design-space-exploration) or for a pure structural-debt inventory that does not need an invariant boundary (technical-debt-audit).

Use this skill when the user wants to add test coverage targeting blind spots in a specific method — uncovered branches, edge cases, or unusual inputs. Activate on explicit requests to cover blind spots or when the user asks "what should I test here?" about a particular method. This is not about achieving 100% line coverage, but about ensuring the method behaves correctly in scenarios that are easy to miss.

Build a directed graph connecting causes (inputs, preconditions) to effects (outputs, actions) through AND/OR/NOT logic nodes, then mechanically derive a decision table from it — for when conditional logic is too tangled to see clearly in prose or needs to be communicated visually to non-technical stakeholders. Use when the user has complex validation logic with nested conditions (more than ~5 interacting conditions), says the spec seems to have implicit logical structure they can't quite see, or needs to communicate business rules to stakeholders via a diagram. For straightforward conditional logic with 5 or fewer conditions, the decision-tables skill is the faster, more direct path to the same result — reach for this only when the graph itself adds clarity.

Shrink an exponential combination space (feature flags, config options, API parameters) down to a minimal test matrix that still guarantees every pair of values is covered — pairwise/all-pairs testing, escalating to orthogonal arrays when 3-way interaction coverage is needed. Use eagerly whenever the user has 4+ independent parameters or flags and wants a test suite for them, mentions "too many combinations to test", "feature flag combinations", "config options interacting badly", "pairwise testing", "all-pairs", "orthogonal array", or describes a system where multiple independent settings can combine in ways nobody has fully tested. Don't reach for this when parameters are tightly interdependent (that's a decision-tables problem) or when there are only 2-3 conditions (exhaustive enumeration is cheaper than setting up pairwise coverage).

End-of-session hill climb on the instruction surface. Encodes this session's friction into AGENTS.md, skills, or project docs so the next session does not pay the same tax.

Build a decision table that maps every meaningful combination of conditions to a specific outcome, and flags the combinations nobody has specified. Use eagerly whenever behavior is governed by combinations of independent yes/no conditions — authorization rules ("if role is admin AND resource is active AND user owns it..."), validation logic with multiple interacting constraints, discount/pricing stacking rules, feature-gating logic, or any business rule the user would naturally sketch as a truth table. Trigger on "what happens when multiple conditions apply", "map out these rules", "decision table", "truth table", "combination of conditions", or "what if a user qualifies for more than one X". If the problem also involves numeric ranges, states, or many independent parameters beyond simple yes/no conditions, the scenario-design skill can help route to the better-fitting technique instead.

Map the dimensions along which an architectural or design decision can vary, place known options in that space, and surface the unexplored regions and implicit assumptions before a decision gets locked in. Use eagerly when the user is deciding *how* to build something and multiple valid approaches exist — sync vs. async, monolith vs. services, REST vs. GraphQL, storage tier choices, algorithm/data-structure selection — or asks "what are all the ways we could solve this", "what are we not considering", "help me think through this design tradeoff", or wants a systematic pass before committing to an architecture. Unlike the other scenario-design techniques, this isn't about testing an existing system — it's about reasoning about the space of possible systems before one is built. If the goal is instead to enumerate test scenarios for something already built or specified, another scenario-design technique fits better.

Turn a parameter's valid/invalid ranges into a systematic set of test cases by partitioning the input space into equivalence classes and probing the boundaries between them, where bugs disproportionately cluster. Use eagerly whenever the user needs test cases for numeric ranges (age, quantity, price, days), string length constraints, date/time windows, or enumerated sets — especially when they say "what test cases should I write for this", "what are the edge cases", "boundary values", "off-by-one", or describe a method with documented min/max constraints on its parameters. Also trigger when they mention validation logic for a range-constrained input and aren't sure what to check beyond the happy path. If the problem is really about combinations of many independent parameters rather than the boundaries of one, the scenario-design skill can route to combinatorial-testing instead.

Systematically enumerate failure modes for a system or process, score each by severity, likelihood, and detectability, and produce a prioritized risk register (Risk Priority Number = S × O × D). Use eagerly whenever the user asks "what could go wrong", wants a pre-launch risk review of a critical feature, is turning an incident postmortem into a broader risk analysis, needs a documented risk assessment for compliance, or describes a new system/integration where failure modes haven't been catalogued yet. Trigger on "failure modes", "risk register", "what are the risks here", "RPN", "risk priority", or "what should we worry about before we ship this". Prefer this over scenario-analysis when the output needs to be quantified and prioritized rather than narrative; if the user wants stakeholder-facing stories instead of a scored register, the scenario-analysis skill fits better.

Create or update a personal operator profile under ~/.agents/projects/ — who the operator is, skill calibration, and collaboration preferences for this project. Only invoke when the user explicitly runs /operator-setup. Do not auto-trigger based on context.

Use this skill when the user wants to audit code consistency issues — when the same problem is solved in different ways across the codebase. Activate on /realign.

Build a set of named, narrative scenarios — each a coherent story of who does what under what conditions and what should happen — to find requirements gaps and give stakeholders a shared vocabulary to validate against. Use eagerly for requirements analysis, checking whether user stories or acceptance criteria cover all relevant situations, API usage documentation, or regulatory/compliance contexts where scenarios need sign-off. Trigger on "what scenarios are we missing", "walk through the use cases", "does this cover all the ways a user could hit this", or when the "who" and "why" matter as much as the technical "what". Not the right fit for exhaustive combinatorial coverage (use decision-tables or combinatorial-testing) or quantified risk prioritization (use fmea) — scenario-analysis is for meaningful, humanly-reasoned-about situations, not exhaustive enumeration.

Diagnose the shape of a scenario-enumeration problem (multiple variables, states, conditions, or failure modes) and route to the right systematic technique — decision-tables, equivalence-partitioning-bva, combinatorial-testing, state-transition-testing, fmea, design-space-exploration, scenario-analysis, or cause-effect-graphing. Use this eagerly when the user asks "what cases should I handle?", "what could go wrong?", "am I missing any scenarios?", "how do I systematically test/model this?", or describes a problem that could plausibly need more than one of those techniques (e.g. an entity with both range-constrained fields and a state machine), and it isn't obvious yet which one(s) fit. If the user already knows which technique they want (they name it, or describe a problem shape that maps cleanly to exactly one — e.g. "map out this state machine" or "what could go wrong with this integration") jump straight to that technique's own skill instead; this skill's job is diagnosis and combination, not narrow application.

Model a system as states connected by event-triggered transitions, and find the (state, event) combinations nobody has defined — missing transitions, unreachable states, trap states, and undefined invalid-transition handling. Use eagerly whenever the user describes an entity with a status field that changes based on events (order lifecycle, payment states, approval workflows, auth flows, wizard/multi-step forms, protocol states) and wants to find gaps in the transition logic, or asks "what transitions are we missing", "can this get stuck", "map out this state machine", or "what happens if this event fires in the wrong state". If the problem is really about combinations of independent input parameters rather than a stateful entity, the scenario-design skill can route elsewhere.

Identify structural problems in a codebase and write them up as technical debt documentation — one file per issue in a subfolder, plus an index. Use this skill when the user asks about structural problems, code smells, maintainability issues, architectural concerns, god classes, tight coupling, or "what's wrong with this code at a high level." Also use it when the user says things like "what should we clean up", "where is this hard to change", "what are the pain points", or "document our tech debt." The skill produces actionable write-ups, not vague observations.