Break through a hard problem with ak:problem-solving

Use ak:problem-solving when progress is blocked by complexity, conventional thinking, recurring patterns, hidden assumptions, or uncertainty about scale. The Skill selects a focused reasoning technique, applies it systematically, and records insights you can validate before planning or implementation.

Choose ak:problem-solving when you are genuinely stuck

Use ak:problem-solving when

• Similar behavior has accumulated many implementations or special cases.
• Familiar approaches are inadequate and you need a new framing.
• The same problem shape appears across several parts of a system.
• A proposed solution depends on an unquestioned “must.”
• Production limits, edge cases, or scale behavior remain unclear.
• You cannot tell which reframing technique fits the obstacle.

Choose another workflow when

• Code is broken, a test fails, or behavior is wrong. Use a debugging or fix workflow to prove the root cause.
• You need repository facts or file locations. Use ak:scout.
• You need an accepted delivery contract or comparison of implementation approaches. Use ak:brainstorm.
• You need a phased implementation plan. Use ak:plan.
• You already know the correction and want it implemented. Use ak:cook.

Prepare the project and runtime

Before you start:

• Complete Onboarding, and confirm Engineer Kit is installed for the runtime and scope you are using.
• Describe the exact obstacle, not only the desired solution.
• Include what has already been tried, the evidence that ruled it out, and the constraints believed to be fixed.
• Provide representative examples, scale assumptions, or repeated cases when they are central to the problem.
• Keep relevant project evidence available so generated insights can be tested.

Run the Skill

/ak:problem-solving "Draft persistence has four storage paths, each with different retry and cleanup rules. Every new editor state adds another branch. Find a simpler model without changing the stored document format."

/ak:problem-solving "Draft persistence has four storage paths, each with different retry and cleanup rules. Every new editor state adds another branch. Find a simpler model without changing the stored document format."

$ak:problem-solving "Draft persistence has four storage paths, each with different retry and cleanup rules. Every new editor state adds another branch. Find a simpler model without changing the stored document format."

The Skill accepts one problem description and dispatches by symptom. It has no published mode flag.

Match the obstacle to a technique

Techniques can be combined after one focused attempt. Useful sequences include finding a recurring pattern before simplifying it, or testing an inverted model at scale.

Describe the problem clearly

Useful input gives the Skill:

• Symptom: the concrete form of stuckness.
• Current model: how the system or decision works today.
• Evidence: examples, measurements, failed attempts, or repeated cases.
• Constraints: what is proven fixed and what is only assumed fixed.
• Success test: the observation that would show a reframing is useful.

For the draft example, list the four paths, the common lifecycle they share, the branches that keep growing, existing compatibility requirements, and a test showing whether one abstraction can handle every current case.

Understand what happens during a run

1. The Skill classifies the obstacle. It matches the concrete symptom to one primary technique rather than applying every framework at once.
2. The Skill loads the focused method. It uses only the detailed guidance needed for the chosen technique.
3. The Skill applies the method. It inventories variants, forces a metaphor, abstracts repeated shapes, flips assumptions, or tests scale extremes according to the selected method.
4. The Skill tests boundaries. It identifies where the proposed insight does not fit and distinguishes a useful reframing from an unsafe or decorative analogy.
5. The Skill records what worked and failed. It states the resulting insight, the evidence still needed, and why a discarded direction failed.
6. The Skill combines techniques only when needed. If the first method does not resolve the obstacle, it selects a complementary technique or recommends a smaller problem, fresh perspective, or different workflow.

Keep approval and safety with you

Important boundaries:

• A metaphor is useful only where its behavior maps to the real system; the Skill must identify where it breaks.
• An inverted assumption is rejected when it creates an unsafe condition, such as trusting unvalidated input.
• A scale game is a reasoning exercise unless actual measurements or load tests are supplied. “One thousand times larger” is not itself performance evidence.
• A simplification is valid only when all required current cases fit cleanly and acceptance behavior remains intact.
• The Skill should not edit product code or turn an insight into an implementation without a separate approved workflow.
• No external provider, credential, cost, or publication is required by the source-defined workflow.

Verify the result

A complete result should give you:

• The identified stuck type and selected technique.
• The evidence and assumptions used during reframing.
• A step-by-step application of the technique at a useful level of abstraction.
• One or more candidate insights with explicit failure boundaries.
• A record of attempted directions that did not hold.
• Concrete checks needed to validate the strongest insight.
• A recommended next workflow: more evidence, debugging, brainstorming, planning, or implementation.

Treat an insight as ready for planning only when it explains the observed cases, respects confirmed constraints, and has a bounded validation method.

Troubleshoot or continue

Continue with ak:brainstorm to compare cause-aligned approaches or ak:plan after an insight has passed its evidence checks. Use ak:cook only for an approved implementation contract.

Know the current limits

• The techniques organize reasoning; they do not provide domain facts that were not supplied or inspected.
• Success metrics in the methods are heuristics, not guarantees that abstraction or scale work is valuable.
• Cursor slash invocation is user-verified evidence, not proof of full runtime parity.
• Stable and beta package the same ak:problem-solving techniques and references. Beta runtime changes do not alter this workflow.