Explain change
Explain a pull request, diff, code, implementation change, file, or arbitrary text in simple step-by-step business and technical language, using a clear visual HTML artifact instead of a wall of text, and save every produced document in the corresponding Obsidian Jira task. Use when the user asks what changed, how something works, why it was implemented, or requests an easy graphical walkthrough.From its SKILL.md
npx -y skills add TheBous/thebous-os --skill explain-changeAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
2 things to look at
- no licenseNo license file was found in the repository. Code published without one is not open source by default, so using it at work is a question for whoever answers licensing questions where you are.
- 11 stars11 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
SKILL.md
6.4 KB, as published. Nobody here has run it
Explain Change
Goal
Explain the subject progressively, clearly, and visually. Help the user understand both the business result and the implementation without producing a long unstructured text.
1. Define the subject
Identify the subject and collect only the required context:
- PR: title, description, diff, changed files, tests, and relevant comments;
- local diff or change:
git diff, repository status, commits, and involved files; - code or file: exact content, callers, dependencies, and entry points;
- text or requirement: structure, concepts, consequences, and terms to clarify.
If the subject is ambiguous, ask one clarification. Never invent intent, behavior, data, or motivation: distinguish evidence, inference, and unverified information.
Before reading details, define a guiding question:
- What problem are we trying to solve?
- What behavior do we need to understand?
- What should happen from input to output?
- Which aspects are still unknown?
For a codebase, first map entry points, main components, inputs and outputs, dependencies, and file responsibilities. Do not start with syntax or read the entire repository linearly.
Form an initial hypothesis and verify it in the code. Always separate:
- Evidence — directly visible in code, diff, tests, or documentation;
- Inference — reasonable but unproven interpretation;
- Unverified — behavior requiring a test, environment, or external clarification.
1a. Trace action chains
For each main behavior, start from the observable output and trace backward:
output → producing function → transformation → data source → input/entry point
Follow the chain to the system entry point, noting what happens, why, and where it is implemented. Repeat only for flows needed to explain the change.
2. Build the explanation
Organize the material as:
- Orientation — guiding question, problem, and before/after.
- Map — entry point, components, data, relationships, and verified hypothesis.
- Flow — concrete input-to-output chain, what happens, why, and where.
- Implementation — files, functions, data, states, APIs, dependencies, and responsibilities, with
file:linereferences when available. - Understanding — example, counterexample, limits, risks, and unverified points.
- Verification — test, command, minimal input, or experiment required.
- Final check — five questions the reader can answer without rereading code.
- Summary — at most three key messages.
For every step explain first what happens, then why, then how it is implemented technically. Use short sentences and one idea per block. Expand acronyms and technical terms at first use.
Make claims verifiable with an example, counterexample, prediction, or small
experiment. If a question cannot be answered from the sources, mark it
explicitly as Unverified.
3. Create the HTML artifact
Always create at least one self-contained HTML file unless the user explicitly asks for a chat-only answer.
- Use a dedicated temporary directory such as
${TMPDIR:-/tmp}/thebous-os-explain-<slug>-<timestamp>. - For a small explanation create
index.html. - For a large feature create
index.htmlplus linked pages for each flow, domain, or technical area. - If the user specifies a destination directory, use it.
- Report absolute artifact paths and, when supported, offer to open
index.html.
Visual requirements
- use inline CSS or local files; no CDNs, external fonts, or remote JavaScript;
- use cards, timelines, numbered steps, callouts, and short tables;
- represent flows and relationships with inline SVG or HTML/CSS diagrams;
- show business and technical paths separately, connecting related decisions;
- make the map, input → output flow, backward chain, example/counterexample, and evidence/inference/unverified distinction visible;
- include short annotated code snippets only when useful;
- keep readable width, accessible contrast, clear headings, and responsive layout;
- do not use one long text block or a decorative visualization that hides essential information.
Include a short header with subject, date, sources, and certainty level. Label inferences and unchecked parts as such. End with adapted versions of:
- What problem does the change solve?
- What is the main data path?
- What is the most important technical decision?
- What happens in edge cases?
- How can I verify the behavior?
Answers must be recoverable from the artifact except for points marked
Unverified.
4. Save all artifacts to the Obsidian task
Identify the Jira task (<KEY>) from the PR, branch, commit, or request context.
If it cannot be determined, ask one clarification and do not invent the key.
Save every generated file in Dev/Tickets/<KEY>/docs/explain-change/<slug>-<timestamp>/,
including linked pages, CSS, images, and local assets. Never overwrite an earlier
explanation. Follow references/obsidian-log.md and use the shared helpers:
source "scripts/helpers.sh"
if [ -f "$ENV_FILE" ]; then load_env; fi
if [ -z "${OBSIDIAN_VAULT_PATH:-}" ] || [ ! -d "${OBSIDIAN_VAULT_PATH}" ]; then
echo "Cannot save the explanation: Obsidian is not configured or the vault does not exist."
# Ask the user to configure the vault before declaring completion.
else
DEST_DIR=$(obsidian_copy_ticket_docs "${OBSIDIAN_VAULT_PATH}" "<KEY>" "explain-change/<slug>-<timestamp>" <ARTIFACT_DIR>)
PLAN_FILE=$(obsidian_ensure_ticket_file "${OBSIDIAN_VAULT_PATH}" "<KEY>" "plan.md")
obsidian_append_section "$PLAN_FILE" "Visual explanation: [open index.html](docs/explain-change/<slug>-<timestamp>/index.html)"
fi
5. Final response
Present only a navigable summary:
- one orientation sentence;
- three to seven main steps;
- the absolute HTML artifact path;
- unverified points or open questions.
Do not paste the complete HTML or produce a wall of text. Do not modify code, PRs, or repository documents: this skill explains and creates artifacts but does not implement fixes.