Trace Demo Learning

Trace Demo Learning

Use this skill to turn a technical topic into a runnable, traceable learning artifact. The goal is not only to answer the question, but to help the user follow the full transformation chain from the initial input to the final result.

Workflow

1. Confirm that the user explicitly invoked the skill name.
2. Convert the user's topic into the smallest meaningful executable demo.
3. Write a runnable script whose main() function clearly exposes the execution path.
4. Decide whether the topic needs one or more visualizations.
5. If visualization would materially improve understanding, write a dedicated plotting script and generate image files.
6. Run the script and capture the output log.
7. Write or refresh a markdown teaching document that explains how to read the log, clarifies the technical terms used in the log, explains the formulas and transitions behind the numbered blocks, and references any generated images.
8. Ask whether the explanation is clear enough.
9. If the user points out unclear parts, refine the code, logs, images, and teaching document and repeat until the user says they fully understand.

Input Scope

Accept both narrow terms and broader technical questions, for example:

1. 用 trace_demo_learning 解释什么是 OCR 技术
2. 用 trace_demo_learning 详细介绍下支持向量机的底层原理
3. 用追溯代码样例学习法解释 Transformer 的注意力打分
4. use trace-demo-learning to explain how BERT builds contextual representations

The topic does not need to be a single term. It can be any programming or computer-science question, as long as the answer can be clarified with a minimal runnable demo.

Output Contract

Always produce these artifacts:

1. A minimal runnable script under the user's working area.
2. A raw log file that stores the runnable script output.
3. A markdown teaching document that explains the log instead of duplicating the full log.
4. A plotting script and image files when visualization is useful.
5. A closing question asking what still feels unclear.

Read references/output-contract.md before generating or updating the markdown document.

Reading Experience Rules

Design the artifacts so the user can tell what to read first within a few seconds.

1. The raw log should begin with a numbered orientation block, preferably [0], that tells the user:
   • what this demo is about
   • which blocks form the shortest useful reading path
   • when it is worth looking at an image
   • which image filename is relevant at that moment
2. Do not push the user to look at an image before they have seen the underlying input, data, or object.
3. If images exist, mention the image filename in the relevant log blocks so the reader can connect the printed values to the matching visual.
4. The markdown document should begin with a short recommended reading path that tells the user:
   • what to look at first
   • which log blocks matter most
   • where the helpful images fit into that path
5. The markdown document should include a quick artifact index so the user can immediately find:
   • the runnable script
   • the raw log
   • the plotting script
   • the generated images
6. Do not assume the user will read top to bottom. Make each artifact usable as an entry point.
7. Optimize for reducing reader uncertainty before adding more detail.

Script Rules

When writing the demo script:

1. Prefer the smallest example that still shows the real mechanism.
2. Use fixed seeds, tiny tensor sizes, tiny datasets, or tiny toy inputs whenever that improves clarity.
3. Print numbered stages such as [1], [2], [3] so the log can be referenced easily.
4. Treat the script as a teaching script, not just a working script.
5. The main() function should reveal the whole execution path.
6. The main() function should primarily orchestrate named helper functions instead of hiding all logic inline when that improves readability.
7. Add Chinese comments inside main() for each major step, explicitly labeling the order such as "步骤一", "步骤二", "步骤三".
8. Each major main() comment should explain why that step exists, not merely restate the function name.
9. Every major log stage should show:
   • what the current input object is
   • what transformation is happening
   • what new object or result is produced
   • why that step exists
10. If the topic involves matrices, tensors, probabilities, scores, or reshaping, print shapes explicitly.
11. If the topic involves hidden intermediate objects such as parameters, masks, heads, kernels, or embeddings, expose them directly in the log instead of only describing them abstractly.
12. Use the opening orientation block to point the reader to the most helpful blocks and, when relevant, the most helpful image filename.

Log Rules

Treat the raw log as the primary trace of the computation.

1. The main purpose of the log is to show how an input becomes an output step by step.
2. Prefer tracking object flow over writing large concept paragraphs.
3. For each important stage, make the relationship between old objects and new objects explicit.
4. If the topic is iterative or trainable, highlight:
   • the initial state
   • the state before a key update
   • the update itself
   • the state after the update
   • the final state
5. If the topic is a transform pipeline, highlight:
   • the initial input
   • the first transformed object
   • the next transformed object
   • the final output
6. Keep explanations in the log short and execution-oriented. Put deeper terminology and formula explanations mainly in the markdown guide.

Visualization Rules

Add a plotting script when any of the following is true:

1. The demo constructs sample data manually and that data would be easier to understand visually.
2. The topic has a geometric meaning, such as classification boundaries, margins, clusters, trajectories, or nearest points.
3. The topic has a structured intermediate result, such as a matrix, heatmap, attention map, loss curve, confusion matrix, or kernel map.
4. The user asks for a more intuitive or visual explanation.
5. You judge that a picture would reduce cognitive load more effectively than more prose.

When adding a plotting script:

1. Keep it separate from the main trace script.
2. Name it plot_<topic>_demo.py or another clear topic-specific variant.
3. Save image files into the same topic directory as the trace script.
4. Make the images deterministic whenever possible.
5. Prefer one image per teaching point over one overloaded figure.

When adding images:

1. Reference them from the markdown teaching document.
2. Explain what each image is trying to teach.
3. Tell the reader what to focus on in the image.
4. If the image corresponds to specific numbered log blocks, state that mapping explicitly.
5. In the log and markdown body, refer to images by filename only. Do not label them as "图一/图二/图三", and do not show full filesystem paths in the teaching prose.
6. Introduce an image after the user has already seen the relevant input, data, or object in the log or markdown.

Clarity Rules

Use the following teaching bar:

1. Default to Chinese unless the user asks otherwise.
2. Explain new terms where they first appear.
3. Avoid skipping from concept to result without showing the bridge.
4. If the user says a part is unclear, add a narrower trace for that part instead of only rewriting prose.
5. When possible, verify a formula numerically in the log so the user can see that the printed values match the theory.
6. If the user says the materials feel hard to navigate, improve the reading order, artifact index, object-flow trace, and block-to-image mapping before adding more raw detail.

Read references/iteration-loop.md when refining an explanation after user feedback.

Markdown Generation

Use scripts/render_trace_markdown.py when you already have:

1. a topic title
2. a script path
3. a captured log file
4. a destination markdown path

The script wraps the log into a consistent markdown shell. Prefer manual markdown authoring when the topic needs richer teaching notes, glossary sections, formula explanations, image guidance, or numbered-block walkthroughs.

File Responsibilities

Keep the generated artifacts separate:

1. *_trace_demo.log stores the full raw output log and should be the single source of truth for runtime output.
2. *_trace_demo.md should not paste the entire log by default.
3. *_trace_demo.md should explain:
   • what the demo is teaching
   • what to read first and why
   • how to read the numbered log blocks
   • when a specific image filename is worth viewing
   • terms, symbols, formulas, and variables that appear in the log
   • the causal relationship between major numbered blocks
   • what each generated image is showing
   • how each generated image connects to the log or code
4. Open the markdown with useful content immediately. Do not start with low-value statements about what the document is not doing.
5. If a user does not understand a term appearing in the log, expand the markdown explanation first.
6. If the markdown explanation is still not enough, then improve the script output and regenerate the log.

Completion Criteria

Do not stop after the first working demo unless the user explicitly says the explanation is already clear.

The task is complete only when:

1. the script runs successfully
2. the raw log file exists
3. the markdown document exists and explains the log clearly
4. if images would materially help, the plotting script and image files exist
5. generated images are referenced and explained in the markdown
6. the explanation is traceable stage by stage
7. the user has had a chance to point out unclear parts