Decompose and Plan#

The problem this solves#

Local models generate code reactively — they start typing the moment they see the task. This works for trivial tasks but produces mediocre output for anything complex. Sonnet's "extended thinking" mode is essentially a forced decomposition pass before generation.

We can replicate this behavior with M2.7 by requiring it to fill out a structured plan template before any code is written. The act of filling the template is the reasoning step.

The planning prompt#

text

You are planning the implementation of the following task. Your job is NOT
to write code yet — only to plan.

Task: {task}

{rag_context_if_any}

Produce a plan in the following exact JSON structure:

```json
{
  "sub_problems": [
    {
      "title": "short title",
      "description": "one paragraph describing what must be done",
      "depends_on": ["title of prior sub_problem"] or []
    }
  ],
  "apis": [
    {
      "name": "Framework.API.name",
      "version_requirement": "iOS 18+" or "Python 3.11+" or "none",
      "purpose": "why this API is needed"
    }
  ],
  "risks": [
    {
      "risk": "specific thing that could go wrong",
      "mitigation": "how to avoid or handle it",
      "severity": "high" | "medium" | "low"
    }
  ],
  "files_affected": [
    {
      "path": "relative/path/to/file.ext",
      "change_type": "create" | "modify" | "delete"
    }
  ],
  "order": ["sub_problem title", "sub_problem title", ...],
  "estimated_loc": integer
}

Requirements:

1. Break the task into 2-6 sub_problems. Fewer is better if possible.
2. List ALL APIs you will use, including their version requirements. If using iOS/Swift APIs, check iOS 26 deprecations.
3. Identify at least 2 risks. "No risks" is never acceptable — be critical.
4. File list must be complete — no files added later during implementation.
5. Order must be a valid topological sort of sub_problems based on depends_on.
6. Estimated LOC should be realistic. If > 500, flag for decomposition into smaller tasks.

Output ONLY the JSON. No explanation, no preamble, no markdown fences.

text

## Execution

```python
async def decompose_plan(task, rag_context=None, specialist_prompt=None,
                        force_schema=True):
    prompt = PLANNING_PROMPT.format(
        task=task,
        rag_context_if_any=f"\nRelevant context:\n{rag_context}\n" if rag_context else ""
    )

    system = specialist_prompt or "You are a senior engineer planning code."

    response = await llm.generate(
        prompt=prompt,
        model="m27-jangtq-crack",
        system=system,
        temperature=0.2,  # low temp for structured output
        max_tokens=2000
    )

    # Parse JSON
    try:
        plan = json.loads(response.strip().strip("`").strip("json").strip())
    except json.JSONDecodeError:
        # Try to extract JSON from response
        match = re.search(r"\{.*\}", response, re.DOTALL)
        if match:
            plan = json.loads(match.group())
        else:
            if force_schema:
                raise PlanSchemaError("Model did not produce valid JSON")
            return {"error": "parse_failed", "raw": response}

    # Validate schema
    required_keys = {"sub_problems", "apis", "risks", "files_affected",
                     "order", "estimated_loc"}
    missing = required_keys - set(plan.keys())
    if missing and force_schema:
        raise PlanSchemaError(f"Missing keys: {missing}")

    # Validate order is topological
    if not _is_valid_topological(plan["sub_problems"], plan["order"]):
        raise PlanSchemaError("order is not a valid topological sort")

    # Flag if estimated_loc too large
    if plan["estimated_loc"] > 500:
        plan["warning"] = "Task may be too large — consider decomposing further"

    return plan

def _is_valid_topological(sub_problems, order):
    title_to_deps = {sp["title"]: set(sp.get("depends_on", [])) for sp in sub_problems}
    seen = set()
    for title in order:
        if title_to_deps[title] - seen:
            return False
        seen.add(title)
    return True

Using the plan downstream#

The plan becomes part of the context for code generation. Inject it like:

text

You have planned this task as follows:

{plan_as_readable_text}

Implement ONLY the sub_problem "{current_sub_problem}" now.
Do not attempt sub_problems that come later in the order.

This keeps the generation focused on one concern at a time and leverages the decomposition to prevent the model from trying to write everything at once.

Why force the schema#

Without schema enforcement, M2.7 tends to produce prose plans that are easy to generate but hard to use programmatically. Structured JSON forces the model to commit to specifics: exact file paths, exact API versions, exact risk factors. Vagueness becomes syntactically impossible.

When to skip this skill#

For tasks where decomposition adds no value:

• Single-line fixes ("rename this variable")
• Trivial format conversions ("convert this JSON to CSV")
• Questions rather than implementation requests
• Tasks under 30 lines of expected output

The orchestrator handles this triage — decompose-plan is only invoked when it will add value.

Output usage#

The parent orchestrator stores the plan in task.scratchpad["plan"]. Subsequent steps (generation, build-feedback, reflection) read from this plan rather than re-deriving what the task is about.

For iOS tasks specifically, the plan's apis section feeds into:

• RAG query expansion (retrieve docs for those specific APIs)
• Build feedback (validate those APIs are actually available at target iOS version)
• Reflection checklist (verify those APIs are used correctly)

Failure modes#

If M2.7 can't produce a valid plan after 2 retries, escalate to claude-handoff. This is a strong signal that the task is outside local capability — if the model can't even plan it, it certainly can't implement it.