M9 · Write a gotcha page

Goal

• Write up one mistake you made, so that the next person recognizes it from its symptom.
• Explain its mechanism, a check that tells it apart from other causes, and its fix, each backed by a source.
• Get the page through the site’s checks, in English and in Korean and Chinese, or with those pages marked pending.

Before you start

• Read the gotchas to see how they are written, and the template in docs/GOTCHA_TEMPLATE.md in the repository.
• Read PRIVACY_RULES.md: nothing from a real project, and no names of institutions, devices or deployments.

Steps

1. Choose the mistake

Pick a mistake you made yourself, and describe it by what you saw first, before you knew the cause. Strip it of everything that belongs to the project it happened in: the page must be true of any design.

2. Reproduce it

Show the mechanism with the site’s own tools where you can. A converter-level mistake can often be shown in the simulator, as the gotcha on a fixed-duty flyback that pins its source’s voltage does. The simulator’s preset of a buck into a fixed voltage, for example, shows an inductor current that never settles:

▶ Open in the simulator: Buck
Preset from the example sim-buck-fixed

3. Write the page

Follow the template: the tags, then Symptom, Why, How to confirm, Fix and References. Give every number through a synthetic example (examples/synthetic/<name>.yaml, shown with <Val>), or from a cited source on the same line. Link equations with <EqRef>; a new equation goes into equations.yaml first.

4. Back every claim

Cite a source for every statement about a device or a method, from references.bib. A new entry keeps a VERIFY note until its DOI or URL has been opened and matched, and until then no published page may cite it.

5. Run the checks

Run python scripts/modulelint.py, python scripts/privacy_scan.py, python scripts/mathlint.py and python scripts/refcheck.py, then npm run build. Add the page’s row to docs/STATUS.md, write the Korean and Chinese pages or mark them pending there (the Chinese on a row of its own in the Chinese table), and open a pull request if you want it on the site.

Acceptance criteria

• A mistake of your own, described by what you saw first, with nothing from the project it happened in.
• The page follows the template: its tags, then Symptom, Why, How to confirm, Fix and References.
• Every number comes from a synthetic example through <Val>, or from a source cited on the same line.
• Every claim about a device or a method cites a verified entry of references.bib.
• modulelint, privacy_scan, mathlint and refcheck pass, and the site builds.
• A Korean page, or a STATUS row that marks it pending.
• A Chinese page, or a row of STATUS's Chinese table that marks it pending.

Clear this mission

Your ticks stay in this browser only: no account, and nothing is sent.

Gotchas

• A symptom described with the cause already in mind helps no one who has not found the cause yet. Describe what you saw.
• Numbers from the project you were working on are not allowed, even rounded. Make a synthetic example with round values that show the same effect.
• A fix without a check is a guess: say how to tell that the fix worked.

Go deeper

• Application note Impedance Measurement Handbook (5950-3000) — Keysight Technologies · retrieved 2026-09-24
  How LCR meters and impedance analyzers measure, why a component's measured value depends on the test frequency and signal, and how to connect and compensate the test fixture.
• Application note Low Level Measurements Handbook, 7th edition — Keithley Instruments (Tektronix) · retrieved 2026-09-24
  Precision dc measurements, among them low resistances with the four-wire (Kelvin) method, which keeps the test leads' resistance out of the reading.

Quiz

1. Where may a number on a gotcha page come from?

   1. From the project where the mistake happened, rounded
   2. From a synthetic example shown with <Val>, or from a source cited on the same line
   3. From memory
   4. From any web page
   Answer and explanation

   Correct answer: B The privacy rules allow textbook or data-sheet numbers with their source, and synthetic example values; nothing from a real project, even rounded.

2. Which section tells a reader how to be sure the gotcha is what they are seeing?

   1. Symptom
   2. Why
   3. How to confirm
   4. References
   Answer and explanation

   Correct answer: C The same symptom can have several causes. How to confirm gives a measurement or a check that tells this one apart.

3. A new reference still carries a VERIFY note. May the page cite it?

   1. Yes, if the title looks right
   2. No: refcheck fails until the DOI or URL has been opened and matched and the note removed
   3. Yes, in the Korean page only
   4. Only in a footnote
   Answer and explanation

   Correct answer: B An unverified entry may not be cited from a published page, so that no citation points to something nobody has checked.

4. The Korean page is not written yet. What does the site need?

   1. Nothing
   2. A row in docs/STATUS.md that marks the Korean page pending
   3. A machine translation
   4. The English page moved out of 08-gotchas
   Answer and explanation

   Correct answer: B modulelint accepts an English page without its Korean mirror only when STATUS marks the Korean page pending.

5. Why describe the symptom before the cause?

   1. Because the template sorts sections alphabetically
   2. Because the reader who needs the page knows only what they see, not yet why
   3. Because causes are hard to write
   4. It does not matter
   Answer and explanation

   Correct answer: B A gotcha is found by its symptom. Written with the cause in mind, it does not match what the next person sees on the bench.