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 pass that finds issues_found: 0 marks that

dimension as converged

• Convergence is irreversible per run; a converged

dimension is not re-run

• 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
}

This file enables resume across sessions. On resume, skip converged dimensions and continue from the next unconverged dimension.

Subagent Isolation

Each pass dispatches a self-contained subagent to prevent context accumulation. The subagent receives:

• Target directory/files
• Pass type and scope (from pass-definitions module)
• Previous pass results (summary only, not full context)

Subagent dispatch is optional for targets under 100 lines of code; in-session review is sufficient for small files.

Workflow

1. Initialize state file (or load existing) 2. Determine next unconverged dimension 3. Dispatch subagent for that dimension 4. Record results in state file 5. If dimension converged (0 issues), mark it 6. If all dimensions converged or 10 passes reached, stop 7. Otherwise, proceed to next dimension

Cross-References

• pensive:code-refinement - used in clarity pass
• conserve:code-quality-principles - KISS/YAGNI/SOLID
• imbue:latent-space-engineering - frame pass prompts

with emotional framing for better results

Pass Type Definitions

Pass 1: Correctness

Goal: Code works as intended.

Scope:

• Run test suite, identify failures
• Fix failing tests
• Check for runtime errors
• Verify edge cases specified in requirements

Agent prompt focus: "Run all tests. For each failure, identify the root cause and fix it. Do not refactor; focus only on making tests pass."

Tools: Bash (pytest/test runner), Edit

Convergence: 0 test failures

Pass 2: Clarity

Goal: Code is readable and well-structured.

Scope:

• Variable and function naming
• Function length and complexity
• Comment quality (helpful vs. noise)
• Dead code removal
• Single-responsibility adherence

Agent prompt focus: "Review for readability. Rename unclear variables, break up long functions, remove dead code. Do not change behavior."

Tools: Read, Edit, pensive:code-refinement

Convergence: 0 clarity issues found by reviewer

Pass 3: Consistency

Goal: Code follows project conventions.

Scope:

• Naming conventions (snake_case, camelCase, etc.)
• Import ordering
• Error handling patterns
• Logging patterns
• File organization

Agent prompt focus: "Compare against codebase conventions. Flag deviations from established patterns. Use style-gene-transfer if exemplar available."

Tools: Read, Grep, Edit

Convergence: 0 convention deviations found

Pass 4: Polish

Goal: Code is production-ready.

Scope:

• Error messages are user-friendly
• Documentation is accurate and complete
• Edge cases have graceful handling
• Configuration is well-documented

Agent prompt focus: "Review error messages, docs, and edge cases. Ensure each error message helps the user understand what went wrong and how to fix it."

Tools: Read, Edit

Convergence: 0 polish issues found

Pass Ordering

Passes run in order: correctness, clarity, consistency, polish. This ordering is intentional:

1. Fix bugs before cleaning up code 2. Clean up code before checking conventions 3. Check conventions before polishing edges

If a pass in a later dimension discovers a bug (correctness regression), surface to human rather than re-running the converged correctness pass.