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.