micro-edit

name	micro-edit
description	Break large coding tasks into self-contained micro-edits with code examples, constraints, and validation so smaller subagents can execute them safely. Use when the user says "micro-edit", "small changes", "break into tasks", "parallel micro-tasks", or wants to split a large change into reviewable pieces.
compatibility	Works with pi or other coding agents that support Agent Skills and subagent delegation. Falls back to sequential execution when subagents are unavailable.

Micro-Edit Orchestration Skill

Concept

Break large coding tasks into small, reviewable micro-edits that can be executed independently, preferably in parallel by subagents. The main agent should be the highest-capability planner but should stay token-efficient: inspect just enough code to identify boundaries, package narrow context for workers, validate results, and only implement directly when needed. This lets smaller or less capable models succeed because each task includes the exact files, examples, constraints, and validation needed.

When to Use

• User wants to split a large change into smaller pieces
• Multiple independent files need similar changes
• Code review would be more manageable with smaller diffs
• User says: "break it into tasks", "micro-edit", "parallel workers"
• Initial analysis reveals many independent opportunities

Non-Negotiable Rules

1. Micro-tasks must be independently verifiable - each subagent's work can be validated separately
2. Changes must be behavior-preserving - unless explicitly requested
3. Validation happens BEFORE aggregation - don't aggregate untested changes
4. Fail fast on validation errors - stop and fix before continuing
5. Report clearly - user sees progress, not hidden work
6. Degrade gracefully - if subagents are unavailable, run the same micro-tasks sequentially
7. Package context, not ambiguity - each worker task must include the exact files to read, files to modify, examples to imitate, constraints, and validation command

Model Strategy

• Main agent: use the strongest available model as a token-efficient planner, context packer, validator, and aggregator. It should avoid reading the entire codebase or doing all edits unless fallback mode is required.
• Worker agents: may use smaller, cheaper, or less capable models because every task packet is narrow and self-contained.
• Token discipline: prefer targeted searches and 1-3 representative examples over broad codebase dumps. Give workers only the context needed to complete their micro-edit.

Workflow

Phase 1: Plan and Enqueue

1. Analyze the request with minimal context

   • What is the end goal?
   • What files/modules are affected?
   • What are the dependencies between changes?
   • What small set of examples will let a weaker worker imitate the existing pattern?

2. Break into micro-tasks

   • Each task: one file, one feature, or one refactoring pattern
   • Tasks should be understandable by a smaller model and completable in <5 minutes
   • Prefer "read these examples, edit this file" over broad search/refactor instructions
   • Label tasks with priority (H/M/L) and area (e.g., "rust-oauth", "ts-ui")

3. Discover verification commands

   • Inspect project docs and configuration before delegating work
   • Prefer repository-specific commands from README, AGENTS.md, package.json, Cargo.toml, pyproject.toml, Package.swift, etc.
   • Examples: npm test, npm run build, npm run lint, cargo check, cargo test, swift test, xcodebuild test

4. Create context packets

   • For each micro-task, include: task objective, files to read first, files to modify, pattern/example to follow, explicit non-goals, validation command, and report format
   • Keep packets small; do not ask workers to rediscover architecture unless that is the task

5. Create task tracking

   - [ ] Task 1: [description]
   - [ ] Task 2: [description]
   - [ ] ...
   

6. Launch parallel subagents when available

   • Max 4-6 concurrent agents (avoid rate limits and merge conflicts)
   • Each agent gets: task description, files to modify, verification command
   • Use an available implementation/coding subagent. If no generic worker exists, use the closest available coder/developer subagent or run sequentially in the main agent

Phase 2: Execute Independently

Each subagent, or the main agent in fallback mode:

1. Reads the target files
2. Makes only the assigned micro-change
3. Runs the agreed verification command when practical
4. Reports: PASS/FAIL, files changed, lines affected, and any skipped verification

Phase 3: Validate

After execution completes:

1. Check each result - confirm every micro-task reports PASS or a clear skipped-verification reason
2. Validate the combined workspace - run the strongest practical project-level verification
3. Fix failures - if validation fails, stop aggregation and fix immediately
4. Aggregate only validated results - compile findings from agents or sequential steps
5. Report status - clear summary for user

Fallback Mode

If parallel subagents are unavailable or unsafe for the repository state, execute the same plan sequentially in the main agent:

1. Complete one micro-task
2. Validate it
3. Record the result
4. Move to the next micro-task only after the current one passes
5. Stop on the first unresolved failure

Phase 4: Present

1. Summary table

   | Task | Status | Files | Lines |
   |------|--------|-------|-------|
   | OAuth dedup | ✅ PASS | 5 | -200 |
   | Type unification | ✅ PASS | 3 | -50 |
   

2. Total impact

   • Lines removed/added
   • Files changed
   • Tests added/passing

3. Next steps

   • Options for the user: commit, continue, or abort

Output Format

## Micro-Edit Session: [Task Name]

### Tasks Executed

| # | Task | Status | Changes |
|---|------|--------|---------|
| 1 | [H] Extract helper | ✅ PASS | lib.rs +2, adapter.rs -15 |
| 2 | [M] Rename field | ✅ PASS | types.rs +1 |
| ... | ... | ... | ... |

### Validation
- [x] cargo check: PASS
- [x] cargo test: 412 PASS

### Impact
- Files: 8 changed
- Lines: -347 net

### Options
- [A) Commit changes]
- [B) Continue with more tasks]
- [C) Generate report]

Subagent Task Template

When launching subagents, include this structure:

TASK: [One sentence objective]

READ FIRST:
- path/to/example_or_pattern_file.ext
- path/to/relevant_type_or_helper.ext

FILES TO MODIFY:
- path/to/target_file.ext

PATTERN TO FOLLOW:
[Point to the exact function/component/test style to imitate. Explain the smallest relevant pattern.]

ACTION:
1. [Specific step]
2. [Specific step]

VERIFICATION:
Run the project-specific command discovered during planning, such as `cargo check`, `npm test`, `npm run build`, `swift test`, or explain why verification cannot be run

CONSTRAINTS:
- Do NOT change behavior
- Do NOT add new dependencies
- Keep changes minimal
- Do NOT modify files outside FILES TO MODIFY unless explicitly required

REPORT:
- Files changed
- Pattern/example followed
- Validation result
- Any uncertainty or skipped verification

Anti-Patterns to Avoid

• Don't batch too many changes - one subagent per logical unit
• Don't skip validation - always verify before aggregating
• Don't let failures propagate - fix immediately, don't aggregate errors
• Don't hide complexity - user should see what's being done
• Don't assume a specific agent name - use available subagents or fallback mode
• Don't give vague worker prompts - avoid "refactor this area"; provide concrete files, examples, actions, and validation

Example Usage

User: "Extract the duplicated code across these 4 adapters into a shared helper"

Agent:
1. Identifies 4 adapters with ~100 lines of duplicated logic
2. Breaks into:
   - Task 1: Extract base64 parsing (H)
   - Task 2: Extract system message extraction (H)
   - Task 3: Extract role mapping (M)
3. Launches 3 parallel workers
4. Validates each change
5. Aggregates and presents summary