xinywa Coding Helper

Safely implement minimal, well-tested, and local-pattern-consistent code changes in existing codebases with clear understanding, logging, and resumable progr...

Skill: Safe Brownfield Code Change

Purpose

Perform safe, minimal, production-quality code changes across large repositories with resumable execution and machine-optimized indexing.

---

Skill Routing Requirement

This skill MUST only run for COMPLEX_CODE_TASK.

---

Mandatory Repo Access Check (CRITICAL)

Before execution:

• identify repo paths
• verify accessibility
• verify required files exist

If failed:

text

[Error]
Type: REPO_ACCESS_FAILURE
Missing: <path>
Reason: <why>
Required: <what needed>

DO NOT proceed.

---

Execution Visibility (CRITICAL)

• NEVER run silently
• ALWAYS output progress per step
• MUST include status: IN_PROGRESS | BLOCKED | COMPLETED

---

Fail-Fast Handling

Immediately stop if:

• repo checkout timeout (e.g. 78K files case)
• filesystem too large / slow
• command fails repeatedly

Output:

text

[Error]
Type: INFRASTRUCTURE_FAILURE
Stage: <stage>
Reason: <message>
Fix: <action>

---

Phase 1: Progressive Understanding

Rules

• DO NOT scan full repo blindly
• DO incremental expansion only
• ALWAYS log progress
• ALWAYS resumable

---

Process

1. start from entry points
2. expand to dependencies
3. stop when change point identified

---

Mandatory Output

text

[Understand]
File: <path>
Summary: <short machine summary>
Next: <files to explore>

---

Resume Rule

• check progress.log
• skip already processed files
• continue from last step

---

Repository Index (Machine Optimized)

Location

/home/vibe/aksclaw-data/index//

---

Structure

file_index.json:

json

{
  "file": {
    "symbols": ["funcA", "typeB"],
    "deps": ["fileX"],
    "last_used": "ts"
  }
}

---

Rules

• update index after reading file
• reuse index before reading
• prefer index over re-scan
• DO NOT generate human-readable summaries

---

Phase 2: Plan

• minimal change only

• prefer:

  1. local code
  2. repo pattern
  3. k8s pattern

---

Phase 3: Implement

• smallest safe change
• no refactor

---

Phase 4: Validate

• add/update tests
• coverage target: 80% (if measurable)

---

Phase 5: Review

check:

• correctness
• race conditions
• retry/idempotency
• debuggability

---

Confidence & Early Stop

Compute confidence:

0.0–1.0 based on:

• correctness
• validation
• risk

---

Stop if:

• confidence ≥ 0.85
• no major issue
• no failing tests

---

Output

text

[Confidence]
Score: <0-1>
Reason: <why>
Gaps: <missing>

---

Run Output (MANDATORY)

/home/vibe/aksclaw-data/runs/<run_id>/

must include:

• progress.log
• steps/
• final_output.md
• error.log (if failed)

---

Cleanup

COMPLETED:

• keep summary only

FAILED:

• keep all logs

---

Hard Rules

• NEVER guess missing info
• NEVER skip phases
• NEVER run silently
• MUST follow Execution Visibility
• MUST avoid using skill for simple tasks

---

Mental Model

This is a controlled execution system, not free-form coding.