safe-change

Skill: safe-change

WHAT

Purpose and context

• Purpose: modify shared code (a function/class/module with multiple callers) without breaking existing callers.
• Trigger (when to use): Modifying any function, class, or module called from more than one place.
• Non-goals: do not refactor nearby code on a whim, do not write extra tests outside the task scope, do not manually hunt for callers yourself instead of impact-check.

Mental model

symbol dùng chung → impact-check (callers + dependents) → hành vi quan sát được hiện tại → thay đổi tối thiểu → từng caller: tương thích ngược hoặc cập nhật tường minh → test (nếu có) → "Changed X. Verified Y" → verify-before-commit.

Input and output contract

	Field	Required?	Meaning
In	symbol/module to modify + change request	yes	something with more than one caller
In	the module's tests	no	if present, run them; if not, state this explicitly in the commit message
Out	minimal change + callers verified/updated	yes	every caller from step 1 is considered
Out	confirmation sentence "Changed X. Verified Y still works."	yes	then call verify-before-commit
Out	wiki/sources/draft/DDMMYY-<ten>.md	yes (unless 0 artifacts)	output report

Rules and capabilities

• RULE-01 (MUST): Backward compatibility impossible → surface to user before proceeding.
• RULE-02 (MUST): Touch only what task requires — no opportunistic refactoring.
• RULE-03 (MUST): No tests exist → acceptable to note — don't add tests outside task scope.
• Capabilities: query the caller/dependent graph; read + modify code within task scope; run local tests; write draft wiki.

Failure boundaries

• Backward compatibility cannot be maintained → clarify: stop, inform the user before continuing (RULE-01).
• Test red after the change → blocked, do not move on to verify-before-commit.
• No tests → partial is valid: state this explicitly in the commit message, do not write tests yourself.

HOW

Main workflow

Step	Type	Inputs	Action	Outputs/exit	Failure/next
W01	deterministic	symbol	Run skill impact-check	list of callers + dependents	—
W02	judgment	current code	Record the observed behavior (return value, side effect)	behavior baseline	—
W03	effect	request	Minimal change, do not touch nearby code	diff	cannot maintain compatibility → B01
W04	judgment	callers W01	For each caller: verify backward compatibility or explicitly update	all callers considered	—
W05	deterministic	test dir	Find tests, run them if present	rc 0 or note "no tests"	red tests → blocked; no tests → B02
W06	effect	result	Confirm + call verify-before-commit + output report	confirmation sentence + draft	—

Step-by-step details (source of truth for W01–W06):

1. Run impact-check skill — get list of all callers and dependents.
2. Note current observable behaviour (return values, side effects).
3. Make minimal change. Don't touch adjacent code.
4. For each caller from step 1: verify backward-compatible or explicitly update caller.
5. CHECK: ls <test-dir>/*<module>* 2>/dev/null | head -3 — if tests exist, RUN: <test-cmd>. If none, note explicitly in commit message.
6. Confirm: "Changed X. Verified Y still works." Then invoke verify-before-commit.

Branches

ID	Kind	Guard	Behaviour	Skip / failure	Rejoin
B01	recovery	cannot maintain backward compatibility	stop, notify user before proceeding	user does not approve → cancelled	W04 after user approval
B02	conditional_required	no tests for module	state "no tests" explicitly in commit message, do not write new tests	—	W06

Validation and stopping

Proceed condition: every caller in the list impact-check has been considered, and tests (if any) rc 0. Stop at the confirmation sentence + verify-before-commit; do not refactor further on your own.

Examples

• Positive: add optional parameter timeout=30 to fetch_page() has 4 callers → impact-check lists 4 callers, all 4 don't pass the parameter so compatible → module tests green → "Changed fetch_page signature. Verified 4 callers still work." → verify-before-commit.
• Boundary/failure: change return type get_user() from dict to object, 2 callers use user["id"] → cannot maintain compatibility → stop, notify user (B01), do not modify callers without approval.

Delivery — Output Report

After all main skill tasks complete, write a propose draft to the wiki.

Steps

1. Build the filename:

• Format: DDMMYY-<ten>.md
• DDMMYY = today (e.g., 020626 for 2 June 2026)
• <ten> = 2–4 kebab-case words summarising what was done (e.g., landing-page-coteccons, brand-kit-fintech, ingest-auth-spec)

2. Write llmwiki/wiki/sources/draft/DDMMYY-<ten>.md:

---
type: draft
title: "DDMMYY-<ten>"
status: proposed
tags: [<skill-name>, output-report]
timestamp: YYYY-MM-DD
---

# DDMMYY-<ten>
**Type:** draft
**Status:** proposed
**Tags:** <skill-name>, output-report
**Proposed:** YYYY-MM-DD

## What
<One sentence — what this skill invocation produced or decided>

## Output
<Key artefacts, files created/modified, or decisions made>

## Files
| File | Action |
|------|--------|
| `path/to/file` | created / modified |

## Notes
- Invoked via: `/<skill-name>` skill

## Origin
- **Draft:** `wiki/sources/draft/DDMMYY-<ten>.md`
- **Commit:** _(filled by verify-before-commit)_
- **Date promoted:** _(filled by verify-before-commit)_

3. Update wiki index & log:

• llmwiki/wiki/index.md — append one row: | [DDMMYY-<ten>](sources/draft/DDMMYY-<ten>.md) | draft | YYYY-MM-DD |
• llmwiki/wiki/log.md — append: ## YYYY-MM-DD — <skill-name> — <ten>

Skip only when the skill produces zero artefacts and zero decisions (e.g., a pure display mode like /caveman-stats).