Harness Change Narrative

Change Narrative

Purpose

Use this skill to explain a specific engineering change clearly enough that a future agent can commit it, review it, continue it, or debug it without rediscovering the reasoning.

Boundary:

This skill writes change narrative.
harness-knowledge-capture owns structured project memory.

This skill distills facts, rationale, rejected paths, verification context, and next-step caution. It does not create source-of-truth Harness artifacts.

Usage telemetry is a narrow exception: when an existing Harness document materially shapes the change narrative, append one usage event with usage_record.py. This records narrative impact, not raw reading.

Use When

• Preparing a commit message, PR description, merge note, release note, or handoff.
• Summarizing current progress or recent development.
• Explaining which approach was chosen, which approaches were rejected, and why.
• A substantial feature or cross-module change is completed.
• Work is reverted, backed up, forked, temporarily bypassed, or introduced as a compatibility shim.
• A bug fix needs more than a local code diff to understand why it exists.
• A long session is ending and the next session needs a compact recovery point.

Do Not Use As

• A Feature, ADR, Lesson, Evidence, or Backlog creation workflow.
• A replacement for verification.
• A project memory database.
• A reason to write process artifacts when a commit body or short handoff is enough.
• A way to bypass harness-knowledge-capture when structured Harness artifacts are triggered.

Normal Final Response Boundary

A normal final response does not by itself trigger this skill.

• Use this skill when the requested output is a commit message, PR description, handoff, release note, merge note, progress summary, rejected-path explanation, root-cause narrative, or history-aware engineering change explanation.
• Do not use this skill merely because the assistant is about to summarize completed work to the user.
• Do not re-enter harness-knowledge-capture after it has produced a pass or permitted conditional verdict for the same closeout. Link or summarize that verdict instead.
• If the user asks only for the final result, keep the answer concise and reuse existing verification and closeout evidence.

Workflow

1. Identify the change being explained: commit, PR, merge, release, handoff, reverted work, non-trivial bugfix, or history-aware decision.
2. Gather local evidence first: recent commits, changed files, relevant docs, tests run, failures, and user constraints.
3. For non-trivial bug fixes, inspect history around touched files and link the Feature attribution result from harness-knowledge-retrieval when available. Identify when behavior likely changed, the earlier intent, and whether the new fix preserves or revises that intent.
4. Separate facts from interpretation. Facts include files, commits, commands, errors, and observed behavior. Interpretation includes root cause, rejected paths, and design intent.
5. Write the smallest narrative that prevents future confusion.
6. Choose the immediate narrative destination:

• Commit or PR body for change-local context.
• Handoff note for session-local recovery.
• Merge or release note for published context.
• Decision narrative when a formal ADR may be needed but has not been created yet.
• Agent rule draft when a repeated lesson should constrain future agents.

1. If durable project memory is triggered, hand off to harness-knowledge-capture.

Usage Recording

Only record documents that actually shaped the change narrative. Do not record files that were merely opened, skimmed, checked as candidates, or used only to find a path.

When a Feature, ADR, Lesson, Evidence, or AGENTS document materially explains why the change was made, why an alternative was rejected, how the change continues prior intent, or which historical problem it fixes, run:

python /using-harness/scripts/usage_record.py --root  --doc  --doc-type  --task "" --impact shaped_change_narrative

Use shaped_change_narrative for normal commit, PR, handoff, release-note, or progress-summary narratives. Use another allowed impact only when the narrative work also makes a fresh decision such as changed_design or prevented_repeat_failure.

Output Rules

• Lead with what the next agent needs to continue safely.
• Record chosen and rejected approaches when the decision affected architecture, cost, risk, or future debugging.
• Include root cause for bugfixes when known. If unknown, say what evidence is still missing.
• For non-trivial bugfixes, include owning Feature or negative attribution result, likely introducing commit, original intent, current mismatch, Patch History impact, and fix rationale when available.
• Keep handoffs compact enough to be read at session start.
• Prefer concrete project nouns over generic advice.
• Keep agent-rule drafts operational and specific.
• Link or summarize existing spec, plan, verification, Feature, ADR, Lesson, or Evidence artifacts instead of duplicating them.

Commit And PR Narrative

For commit messages and PR bodies, include the smallest useful version of:

• What changed.
• Why the change is needed.
• How the implementation works.
• Why not the tempting alternatives.
• Verification performed.

Do not force a long template into tiny commits. For non-trivial changes, missing why not is a signal that future agents may rediscover the same rejected path.

Report Template

## Change

What changed?

## Why

What problem, goal, or constraint caused this change?

## Rejected Paths

What alternatives were considered and not chosen?

## Verification

What commands, checks, screenshots, or reviews support the result?

## Future Caution

What should the next agent or reviewer keep in mind?

Quick Checks

• Would this help someone debug when or why a bug was introduced?
• Does a non-trivial bugfix narrative say whether the bug was attributed to an existing Feature and whether Patch History was updated?
• Does this explain why an obvious alternative was not used?
• Would this stop the next agent from repeating a costly mistake?
• Is this explaining a specific change, or trying to own structured project memory?
• Does this overlap with an existing source artifact? If yes, link or summarize it instead of duplicating it.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: solitudeTG
• Source: solitudeTG/harness-coding-skills
• License: MIT

Install and usage instructions live in the source repository linked above.