Guide

Problem Space

Problem space maps the terrain before the agent chooses a fix.

Source: docs/problem-space.md

Problem Space

Problem space maps the terrain before the agent chooses a fix.

Framework positionValue
Skill/problem-space
Run after/aim and context construction
Producesproblem-space map
Feeds/problem-statement

The same symptom can point to different terrain:

  • a one-line bug;
  • a missing regression test;
  • unclear ownership;
  • a boundary that lacks an invariant;
  • a system design that keeps producing the same failure.

Those are different maps. A problem statement comes next and chooses the slice.

flowchart LR
    aim[Aim + context pack] --> skill["/problem-space"]
    skill --> terrain[Terrain map]
    terrain --> statement["/problem-statement"]
    statement --> solution["/solution-space"]

Learn

Problem-space work answers, “What is going on?”

Map:

  • systems involved;
  • users, maintainers, operators, or reviewers affected;
  • repeated symptoms;
  • hard constraints;
  • soft constraints;
  • assumed constraints to test;
  • existing evidence and missing evidence;
  • blast radius if wrong;
  • prior attempts or abandoned fixes.

Terrain mapping explains what the implementation is for before the agent starts proposing fixes.

Why real terrain matters

A one-file exercise is often too shallow. The obvious task is the correct task. There is no real reason to use /problem-space or /problem-statement beyond ceremony.

A real project has constraints that change the right solution level:

  • test coverage;
  • CI speed;
  • release pressure;
  • migration risk;
  • downstream users;
  • architecture boundaries;
  • ownership;
  • prior failed fixes;
  • reviewer capacity;
  • data or security risk.

Those constraints determine whether the right next move is Band-Aid, Local Optimum, Reframe, or Redesign.

Practice

Create a problem-space map before selecting a problem statement.

Include:

  • relevant systems and interfaces;
  • affected users, maintainers, operators, and reviewers;
  • repeated symptoms and known triggers;
  • constraints and assumptions;
  • existing evidence and missing evidence;
  • prior attempts;
  • blast radius if the map is wrong.

Then hand the map to problem-statement.md, where you choose the slice for this run.

Artifact

Produce a problem-space map. It must preserve systems, actors, repeated symptoms, constraints, assumptions to test, evidence, prior attempts, and blast radius. A reviewer should be able to see why the chosen problem statement follows from the terrain.

What Good Looks Like

Map sectionExample
Systems involvednotification event ingestion; reminder scheduler; send boundary; duplicate-skip recording
Repeated symptomduplicate reminders can reach the same recipient when trigger paths overlap
Constraintsdo not change notification copy or timing policy in this slice; the fix must be reviewable with a same-recipient, same-idempotency-key regression check
Assumptions to testmore than one trigger path can reach the send boundary; duplicate prevention belongs at the send boundary, not each caller

Review check

Reject the map if:

  • it only restates the symptom;
  • it hides affected maintainers or users;
  • it treats assumed constraints as facts;
  • it omits blast radius;
  • it gives problem-statement.md no basis for choosing a slice.

Go deeper

← What Open Horizons AddsProblem Statement →