dorodango

Dorodango Polishing Workflow

Named after the Japanese art of polishing a ball of dirt into a high-gloss sphere. Applied to code: take the initial implementation (the "mud ball") and refine it through successive quality passes until it shines.

When To Use

• After initial implementation is complete and tests pass
• Code works but needs refinement across multiple quality dimensions
• Preparing code for review or release
• Resuming a previous polishing session

When NOT To Use

• Code does not compile or pass basic tests (fix first)
• Single-dimension improvement needed (use the specific skill directly: pensive:code-refinement, etc.)
• Greenfield design phase (use brainstorming instead)

Pass Sequence

Four quality dimensions, each a self-contained pass:

1. Correctness - run tests, fix failures
2. Clarity - code readability and structure
3. Consistency - naming, patterns, style alignment
4. Polish - documentation, error messages, edges

See modules/pass-definitions.md for detailed scope of each pass type.

Convergence Model

• Each pass targets one dimension
• A dimension converges on a record, never on the passing subagent's own count alone: correctness on the test command's exit code, clarity and consistency on the linter and formatter exit codes plus a reviewer count of 0, polish on a reviewer count of 0 from a fresh subagent that did not make the edits
• A pass that reports issues_found: 0 without the matching exit code recorded in the state file has not converged
• Convergence is reversible: a later pass that finds a regression in a converged dimension un-converges it, and that dimension is re-run before the run completes
• When all 4 dimensions converge, polishing is complete
• Maximum 10 total passes (hard limit)
• If not converged after 10 passes, surface state to human with recommendation to split into smaller units

State Persistence

State tracked in .attune/dorodango-state.json:

{
  "target": "plugins/foo",
  "started_at": "2026-03-18T12:00:00Z",
  "pass_count": 3,
  "passes": [
    {
      "type": "correctness",
      "issues_found": 2,
      "issues_fixed": 2
    },
    {
      "type": "clarity",
      "issues_found": 5,
      "issues_fixed": 5
    },
    {
      "type": "consistency",
      "issues_found": 0
    }
  ],
  "converged_dimensions": ["consistency"],
  "converged": false
}