shithub: pokecrystal

Download patch

ref: ef9b9bb437b9d941f2bf3a966ccf57a181e336b2
parent: bd27c0d8dc1f21a4eb519c4947055c681b530314
author: vulcandth <vulcandth@gmail.com>
date: Sat Jul 9 12:12:02 EDT 2022 

Clean up bugs commented in the source code (#912)

Co-authored-by: Rangi <remy.oukaour+rangi42@gmail.com>


--- a/data/battle/ai/sunny_day_moves.asm
+++ b/data/battle/ai/sunny_day_moves.asm
@@ -1,6 +1,7 @@
 ; AI_SMART prefers these moves during harsh sunlight.
 
 SunnyDayMoves:
+; BUG: "Smart" AI does not encourage Solar Beam, Flame Wheel, or Moonlight during Sunny Day (see docs/bugs_and_glitches.md)
 	db FIRE_PUNCH
 	db EMBER
 	db FLAMETHROWER
--- a/data/events/happiness_probabilities.asm
+++ b/data/events/happiness_probabilities.asm
@@ -9,4 +9,5 @@
 	db -1,             4, HAPPINESS_YOUNGCUT3 ; 10% chance
 
 HappinessData_DaisysGrooming:
+; BUG: Daisy's grooming doesn't always increase happiness (see docs/bugs_and_glitches.md)
 	db -1,             2, HAPPINESS_GROOMING ; 99.6% chance
--- a/data/items/attributes.asm
+++ b/data/items/attributes.asm
@@ -294,6 +294,7 @@
 	item_attribute $9999, HELD_NONE, 0, NO_LIMITS, ITEM, ITEMMENU_NOUSE, ITEMMENU_NOUSE
 ; METAL_COAT
 	item_attribute 100, HELD_STEEL_BOOST, 10, CANT_SELECT, ITEM, ITEMMENU_NOUSE, ITEMMENU_NOUSE
+; BUG: Dragon Scale, not Dragon Fang, boosts Dragon-type moves (see docs/bugs_and_glitches.md)
 ; DRAGON_FANG
 	item_attribute 100, HELD_NONE, 0, CANT_SELECT, ITEM, ITEMMENU_NOUSE, ITEMMENU_NOUSE
 ; ITEM_91
--- a/data/moves/effects.asm
+++ b/data/moves/effects.asm
@@ -575,7 +575,8 @@
 	supereffectivetext
 	checkfaint
 	buildopponentrage
-	effectchance ; bug: duplicate effectchance shouldn't be here
+; BUG: Moves that lower Defense can do so after breaking a Substitute (see docs/bugs_and_glitches.md)
+	effectchance
 	defensedown
 	statdownmessage
 	endmove
@@ -706,6 +707,7 @@
 	applydamage
 	criticaltext
 	supereffectivetext
+; BUG: Moves that do damage and increase your stats do not increase stats after a KO (see docs/bugs_and_glitches.md)
 	checkfaint
 	buildopponentrage
 	defenseup
--- a/data/text/common_2.asm
+++ b/data/text/common_2.asm
@@ -100,6 +100,7 @@
 	text_end
 
 _BoostedExpPointsText::
+; BUG: Five-digit experience gain is printed incorrectly (see docs/bugs_and_glitches.md)
 	text_start
 	line "a boosted"
 	cont "@"
@@ -108,6 +109,7 @@
 	prompt
 
 _ExpPointsText::
+; BUG: Five-digit experience gain is printed incorrectly (see docs/bugs_and_glitches.md)
 	text_start
 	line "@"
 	text_decimal wStringBuffer2, 2, 4
--- a/data/trainers/dvs.asm
+++ b/data/trainers/dvs.asm
@@ -43,6 +43,7 @@
 	dn  7,  8,  8,  8 ; SWIMMERF
 	dn  9,  8,  8,  8 ; SAILOR
 	dn  9,  8,  8,  8 ; SUPER_NERD
+; BUG: RIVAL2 has lower DVs than RIVAL1 (see docs/bugs_and_glitches.md)
 	dn  9,  8,  8,  8 ; RIVAL2
 	dn  9,  8,  8,  8 ; GUITARIST
 	dn 10,  8,  8,  8 ; HIKER
--- a/docs/bugs_and_glitches.md
+++ b/docs/bugs_and_glitches.md
@@ -123,6 +123,7 @@
 +	ret
 +
  CheckFaint_PlayerThenEnemy:
+-; BUG: Perish Song and Spikes can leave a Pokemon with 0 HP and not faint (see docs/bugs_and_glitches.md)
 +.faint_loop
 +	call .Function
 +	ret c
@@ -139,6 +140,7 @@
 
 ```diff
  CheckFaint_EnemyThenPlayer:
+-; BUG: Perish Song and Spikes can leave a Pokemon with 0 HP and not faint (see docs/bugs_and_glitches.md)
 +.faint_loop
 +	call .Function
 +	ret c
@@ -158,10 +160,11 @@
 
 ([Video](https://www.youtube.com/watch?v=rGqu3d3pdok&t=450))
 
-**Fix:** Edit `SpeciesItemBoost` in [engine/battle/effect_commands.asm](https://github.com/pret/pokecrystal/blob/master/engine/battle/effect_commands.asm)
+**Fix:** Edit `SpeciesItemBoost` in [engine/battle/effect_commands.asm](https://github.com/pret/pokecrystal/blob/master/engine/battle/effect_commands.asm):
 
 ```diff
  ; Double the stat
+-; BUG: Thick Club and Light Ball can make (Special) Attack wrap around above 1024 (see docs/bugs_and_glitches.md)
  	sla l
  	rl h
 +
@@ -189,6 +192,7 @@
  DittoMetalPowder:
  	...
 
+-; BUG: Metal Powder can increase damage taken with boosted (Special) Defense (see docs/bugs_and_glitches.md)
 -	ld a, c
 -	srl a
 -	add c
@@ -273,6 +277,7 @@
 
 ```diff
  .finish
+-; BUG: Reflect and Light Screen can make (Special) Defense wrap around above 1024 (see docs/bugs_and_glitches.md)
 -	ld a, [wLinkMode]
 -	cp LINK_COLOSSEUM
 -	jr z, .done
@@ -298,8 +303,8 @@
 **Fix:** Edit `BattleCommand_EffectChance` in [engine/battle/effect_commands.asm](https://github.com/pret/pokecrystal/blob/master/engine/battle/effect_commands.asm):
 
 ```diff
--	; BUG: 1/256 chance to fail even for a 100% effect chance,
--	; since carry is not set if BattleRandom == [hl] == 255
+ .got_move_chance
+-; BUG: Moves with a 100% secondary effect chance will not trigger it in 1/256 uses (see docs/bugs_and_glitches.md)
 -	call BattleRandom
 +	ld a, [hl]
 +	sub 100 percent
@@ -340,10 +345,7 @@
 
 ```diff
  BattleCommand_BellyDrum:
- ; bellydrum
--; This command is buggy because it raises the user's attack
--; before checking that it has enough HP to use the move.
--; Swap the order of these two blocks to fix.
+-; BUG: Belly Drum sharply boosts Attack even with under 50% HP (see docs/bugs_and_glitches.md)
 -	call BattleCommand_AttackUp2
 -	ld a, [wAttackMissed]
 -	and a
@@ -371,6 +373,7 @@
 ```diff
  HandleBerserkGene:
  	...
+-; BUG: Berserk Gene's confusion lasts for 256 turns or the previous Pokémon's confusion count (see docs/bugs_and_glitches.md)
  	ld a, BATTLE_VARS_SUBSTATUS3
  	call GetBattleVarAddr
  	push af
@@ -426,7 +429,8 @@
 
 ```diff
  BattleCommand_DamageCalc:
- ; damagecalc
+ ; Return a damage value for move power d, player level e, enemy defense c and player attack b.
+-; BUG: Confusion damage is affected by type-boosting items and Explosion/Self-Destruct doubling (see docs/bugs_and_glitches.md)
  	...
  .skip_zero_damage_check
 +	xor a ; Not confusion damage
@@ -512,7 +516,8 @@
  	supereffectivetext
  	checkfaint
  	buildopponentrage
--	effectchance ; bug: duplicate effectchance shouldn't be here
+-; BUG: Moves that lower Defense can do so after breaking a Substitute (see docs/bugs_and_glitches.md)
+-	effectchance
  	defensedown
  	statdownmessage
  	endmove
@@ -526,7 +531,7 @@
 **Fix:** Edit `BattleCommand_Counter` in [engine/battle/move_effects/counter.asm](https://github.com/pret/pokecrystal/blob/master/engine/battle/move_effects/counter.asm) and `BattleCommand_MirrorCoat` in [engine/battle/move_effects/mirror_coat.asm](https://github.com/pret/pokecrystal/blob/master/engine/battle/move_effects/mirror_coat.asm):
 
 ```diff
--	; BUG: Move should fail with all non-damaging battle actions
+-; BUG: Counter and Mirror Coat still work if the opponent uses an item (see docs/bugs_and_glitches.md)
  	ld hl, wCurDamage
  	ld a, [hli]
  	or [hl]
@@ -553,8 +558,8 @@
 
 ```diff
  .done
--	; Bug: this will result in a move with PP Up confusing the game.
--	and a ; should be "and PP_MASK"
+-; BUG: A Disabled but PP Up–enhanced move may not trigger Struggle (see docs/bugs_and_glitches.md)
+-	and a
 +	and PP_MASK
  	ret nz
 
@@ -572,9 +577,10 @@
 
 ([Video](https://www.youtube.com/watch?v=tiRvw-Nb2ME))
 
-**Fix:** Edit `PursuitSwitch` in [engine/battle/core.asm](https://github.com/pret/pokecrystal/blob/master/engine/battle/core.asm)
+**Fix:** Edit `PursuitSwitch` in [engine/battle/core.asm](https://github.com/pret/pokecrystal/blob/master/engine/battle/core.asm):
 
 ```diff
+-; BUG: A Pokémon that fainted from Pursuit will have its old status condition when revived (see docs/bugs_and_glitches.md)
  	ld a, $f0
  	ld [wCryTracks], a
  	ld a, [wBattleMonSpecies]
@@ -604,7 +610,7 @@
 
 ```diff
  CheckHiddenOpponent:
--; BUG: This routine is completely redundant and introduces a bug, since BattleCommand_CheckHit does these checks properly.
+-; BUG: Lock-On and Mind Reader don't always bypass Fly and Dig (see docs/bugs_and_glitches.md)
 -	ld a, BATTLE_VARS_SUBSTATUS3_OPP
 -	call GetBattleVar
 -	and 1 << SUBSTATUS_FLYING | 1 << SUBSTATUS_UNDERGROUND
@@ -621,6 +627,7 @@
 
 ```diff
  .got_mon
+-; BUG: Beat Up can desynchronize link battles (see docs/bugs_and_glitches.md)
  	ld a, [wCurBeatUpPartyMon]
  	ld hl, wPartyMonNicknames
  	call GetNickname
@@ -632,8 +639,6 @@
  	ld a, [wCurBeatUpPartyMon]
  	ld c, a
  	ld a, [wCurBattleMon]
--	; BUG: this can desynchronize link battles
--	; Change "cp [hl]" to "cp c" to fix
 -	cp [hl]
 +	cp c
  	ld hl, wBattleMonStatus
@@ -655,6 +660,7 @@
 
 ```diff
  .only_one_beatup
+-; BUG: Beat Up works incorrectly with only one Pokémon in the party (see docs/bugs_and_glitches.md)
  	ld a, BATTLE_VARS_SUBSTATUS3
  	call GetBattleVarAddr
  	res SUBSTATUS_IN_LOOP, [hl]
@@ -667,6 +673,7 @@
 
 ```diff
  .only_one_beatup
+ ; BUG: Beat Up works incorrectly with only one Pokemon in the party (see docs/bugs_and_glitches.md)
  	ld a, BATTLE_VARS_SUBSTATUS3
  	call GetBattleVarAddr
  	res SUBSTATUS_IN_LOOP, [hl]
@@ -678,7 +685,7 @@
 
 ### Beat Up may fail to raise Substitute
 
-*Fixing this cosmetic bug will* not *break link battle compatibility.*
+*Fixing this cosmetic bug will* **not** *break link battle compatibility.*
 
 This bug prevents Substitute from being raised if Beat Up was blocked by Protect or Detect.
 
@@ -685,6 +692,7 @@
 **Fix:** Edit `BattleCommand_FailureText` in [engine/battle/effect_commands.asm](https://github.com/pret/pokecrystal/blob/master/engine/battle/effect_commands.asm).
 
 ```diff
+-; BUG: Beat Up may fail to raise Substitute (see docs/bugs_and_glitches.md)
  	cp EFFECT_MULTI_HIT
  	jr z, .multihit
  	cp EFFECT_DOUBLE_HIT
@@ -703,14 +711,11 @@
 
 ### Beat Up may trigger King's Rock even if it failed
 
-This bug is caused because Beat Up never sets `wAttackMissed`, even when no Pokémon was able to attack (due to being fainted or having a status condition).
-
 **Fix:** Edit `BattleCommand_BeatUpFailText` in [engine/battle/move_effects/beat_up.asm](https://github.com/pret/pokecrystal/blob/master/engine/battle/move_effects/beat_up.asm):
 
 ```diff
  BattleCommand_BeatUpFailText:
- ; beatupfailtext
-
+-; BUG: Beat Up may trigger King's Rock even if it failed (see docs/bugs_and_glitches.md)
  	ld a, [wBeatUpHitAtLeastOnce]
  	and a
  	ret nz
@@ -732,8 +737,7 @@
 
 ```diff
  BattleCommand_Present:
- ; present
-
+-; BUG: Present damage is incorrect in link battles (see docs/bugs_and_glitches.md)
 -	ld a, [wLinkMode]
 -	cp LINK_COLOSSEUM
 -	jr z, .colosseum_skippush
@@ -762,6 +766,7 @@
 
 ```diff
  BattleCommand_HappinessPower:
+-; BUG: Return and Frustration deal no damage when the user's happiness is low or high, respectively (see docs/bugs_and_glitches.md)
  	...
  	call Multiply
  	ld a, 25
@@ -782,7 +787,9 @@
 
 ```diff
  BattleCommand_FrustrationPower:
+-; BUG: Return and Frustration deal no damage when the user's happiness is low or high, respectively (see docs/bugs_and_glitches.md)
  	...
+-; BUG: Return and Frustration deal no damage when the user's happiness is low or high, respectively (see docs/bugs_and_glitches.md)
  	call Multiply
  	ld a, 25
  	ldh [hDivisor], a
@@ -804,6 +811,7 @@
 **Fix:** Edit `ItemAttributes` in [data/items/attributes.asm](https://github.com/pret/pokecrystal/blob/master/data/items/attributes.asm):
 
 ```diff
+-; BUG: Dragon Scale, not Dragon Fang, boosts Dragon-type moves (see docs/bugs_and_glitches.md)
  ; DRAGON_FANG
 -	item_attribute 100, HELD_NONE, 0, CANT_SELECT, ITEM, ITEMMENU_NOUSE, ITEMMENU_NOUSE
 +	item_attribute 100, HELD_DRAGON_BOOST, 10, CANT_SELECT, ITEM, ITEMMENU_NOUSE, ITEMMENU_NOUSE
@@ -821,6 +829,7 @@
 **Fix:** First, edit `SendOutMonText` in [engine/battle/core.asm](https://github.com/pret/pokecrystal/blob/master/engine/battle/core.asm):
 
 ```diff
+-; BUG: Switching out or switching against a Pokémon with max HP below 4 freezes the game (see docs/bugs_and_glitches.md)
  	; compute enemy health remaining as a percentage
  	xor a
  	ldh [hMultiplicand + 0], a
@@ -919,6 +928,7 @@
  	...
  	criticaltext
  	supereffectivetext
+-; BUG: Moves that do damage and increase your stats do not increase stats after a KO (see docs/bugs_and_glitches.md)
 +	defenseup
 +	statupmessage
  	checkfaint
@@ -953,7 +963,7 @@
 
 ### HP bar animation is slow for high HP
 
-*Fixing this cosmetic bug will* not *break link battle compatibility.*
+*Fixing this cosmetic bug will* **not** *break link battle compatibility.*
 
 ([Video](https://www.youtube.com/watch?v=SE-BfsFgZVM))
 
@@ -960,17 +970,13 @@
 **Fix:** Edit `LongAnim_UpdateVariables` in [engine/battle/anim_hp_bar.asm](https://github.com/pret/pokecrystal/blob/master/engine/battle/anim_hp_bar.asm):
 
 ```diff
--	; This routine is buggy. The result from ComputeHPBarPixels is stored
--	; in e. However, the pop de opcode deletes this result before it is even
--	; used. The game then proceeds as though it never deleted that output.
--	; To fix, uncomment the line below.
+-; BUG: HP bar animation is slow for high HP (see docs/bugs_and_glitches.md)
  	call ComputeHPBarPixels
--	; ld a, e
 +	ld a, e
  	pop bc
  	pop de
  	pop hl
--	ld a, e ; Comment or delete this line to fix the above bug.
+-	ld a, e
  	ld hl, wCurHPBarPixels
  	cp [hl]
  	jr z, .loop
@@ -982,7 +988,7 @@
 
 ### HP bar animation off-by-one error for low HP
 
-*Fixing this cosmetic bug will* not *break link battle compatibility.*
+*Fixing this cosmetic bug will* **not** *break link battle compatibility.*
 
 ([Video](https://www.youtube.com/watch?v=9KyNVIZxJvI))
 
@@ -990,10 +996,8 @@
 
 ```diff
  	ld b, 0
--; This routine is buggy. If [wCurHPAnimMaxHP] * [wCurHPBarPixels] is
--; divisible by HP_BAR_LENGTH_PX, the loop runs one extra time.
--; To fix, uncomment the line below.
  .loop
+-; BUG: HP bar animation off-by-one error for low HP (see docs/bugs_and_glitches.md)
  	ld a, l
  	sub HP_BAR_LENGTH_PX
  	ld l, a
@@ -1000,7 +1004,6 @@
  	ld a, h
  	sbc $0
  	ld h, a
--	; jr z, .done
 +	jr z, .done
  	jr c, .done
  	inc b
@@ -1019,6 +1022,7 @@
 
 ```diff
 -; If the opponent is transformed, fail.
+-; BUG: A Transformed Pokémon can use Sketch and learn otherwise unobtainable moves (see docs/bugs_and_glitches.md)
 +; If the user is transformed, fail.
 -	ld a, BATTLE_VARS_SUBSTATUS5_OPP
 +	ld a, BATTLE_VARS_SUBSTATUS5
@@ -1030,8 +1034,6 @@
 
 ### Catching a Transformed Pokémon always catches a Ditto
 
-This bug can affect Mew or Pokémon other than Ditto that used Transform via Mirror Move or Sketch.
-
 **Fix:** Edit `PokeBallEffect` in [engine/items/item_effects.asm](https://github.com/pret/pokecrystal/blob/master/engine/items/item_effects.asm):
 
 ```diff
@@ -1040,9 +1042,7 @@
  	push af
  	set SUBSTATUS_TRANSFORMED, [hl]
 
--; This code is buggy. Any wild Pokémon that has Transformed will be
--; caught as a Ditto, even if it was something else like Mew.
--; To fix, do not set [wTempEnemyMonSpecies] to DITTO.
+-; BUG: Catching a Transformed Pokémon always catches a Ditto (see docs/bugs_and_glitches.md)
  	bit SUBSTATUS_TRANSFORMED, a
 -	jr nz, .ditto
 -	jr .not_ditto
@@ -1077,13 +1077,12 @@
 
 ([Video](https://www.youtube.com/watch?v=SXH8u0plHrE))
 
-This can bring Pokémon straight from level 1 to 100 by gaining just a few experience points.
-
 **Fix:** Edit `CalcExpAtLevel` in [engine/pokemon/experience.asm](https://github.com/pret/pokecrystal/blob/master/engine/pokemon/experience.asm):
 
 ```diff
  CalcExpAtLevel:
  ; (a/b)*n**3 + c*n**2 + d*n - e
+-; BUG: Experience underflow for level 1 Pokémon with Medium-Slow growth rate (see docs/bugs_and_glitches.md)
 +	ld a, d
 +	dec a
 +	jr nz, .UseExpFormula
@@ -1115,6 +1114,8 @@
 **Fix:** Edit `PokeBallEffect` in [engine/items/item_effects.asm](https://github.com/pret/pokecrystal/blob/master/engine/items/item_effects.asm):
 
 ```diff
+ PokeBallEffect:
+-; BUG: The Dude's catching tutorial may crash if his Poké Ball can't be used (see docs/bugs_and_glitches.md)
  	ld a, [wBattleMode]
  	dec a
  	jp nz, UseBallInTrainerBattle
@@ -1141,17 +1142,13 @@
 **Fix:** Edit `PokeBallEffect` in [engine/items/item_effects.asm](https://github.com/pret/pokecrystal/blob/master/engine/items/item_effects.asm):
 
 ```diff
--; This routine is buggy. It was intended that SLP and FRZ provide a higher
--; catch rate than BRN/PSN/PAR, which in turn provide a higher catch rate than
--; no status effect at all. But instead, it makes BRN/PSN/PAR provide no
--; benefit.
--; Uncomment the line below to fix this.
+ .statuscheck
+-; BUG: BRN/PSN/PAR do not affect catch rate (see docs/bugs_and_glitches.md)
  	ld b, a
  	ld a, [wEnemyMonStatus]
  	and 1 << FRZ | SLP_MASK
  	ld c, 10
  	jr nz, .addstatus
--	; ld a, [wEnemyMonStatus]
 +	ld a, [wEnemyMonStatus]
  	and a
  	ld c, 5
@@ -1171,9 +1168,7 @@
 **Fix:** Edit `MoonBallMultiplier` in [engine/items/item_effects.asm](https://github.com/pret/pokecrystal/blob/master/engine/items/item_effects.asm):
 
 ```diff
--; Moon Stone's constant from Pokémon Red is used.
--; No Pokémon evolve with Burn Heal,
--; so Moon Balls always have a catch rate of 1×.
+-; BUG: Moon Ball does not boost catch rate (see docs/bugs_and_glitches.md)
  	push bc
  	ld a, BANK("Evolutions and Attacks")
  	call GetFarByte
@@ -1189,13 +1184,14 @@
 **Fix:** Edit `LoveBallMultiplier` in [engine/items/item_effects.asm](https://github.com/pret/pokecrystal/blob/master/engine/items/item_effects.asm):
 
 ```diff
- .wildmale
+ .got_wild_gender
 
+-; BUG: Love Ball boosts catch rate for the wrong gender (see docs/bugs_and_glitches.md)
  	ld a, d
  	pop de
  	cp d
  	pop bc
--	ret nz ; for the intended effect, this should be "ret z"
+-	ret nz
 +	ret z
 ```
 
@@ -1206,6 +1202,7 @@
 
 ```diff
  .loop
+-; BUG: Fast Ball only boosts catch rate for three Pokémon (see docs/bugs_and_glitches.md)
  	ld a, BANK(FleeMons)
  	call GetFarByte
 
@@ -1213,7 +1210,7 @@
  	cp -1
  	jr z, .next
  	cp c
--	jr nz, .next ; for the intended effect, this should be "jr nz, .loop"
+-	jr nz, .next
 +	jr nz, .loop
  	sla b
  	jr c, .max
@@ -1222,17 +1219,16 @@
 
 ### Heavy Ball uses wrong weight value for three Pokémon
 
+`HeavyBall_GetDexEntryBank` gets the wrong bank for Kadabra (64), Tauros (128), and Sunflora (192).
+
 **Fix:** Edit `HeavyBall_GetDexEntryBank` in [engine/items/item_effects.asm](https://github.com/pret/pokecrystal/blob/master/engine/items/item_effects.asm):
 
 ```diff
  HeavyBall_GetDexEntryBank:
--; This function is buggy.
--; It gets the wrong bank for Kadabra (64), Tauros (128), and Sunflora (192).
--; Uncomment the line below to fix this.
+-; BUG: Heavy Ball uses wrong weight value for three Pokemon (see docs/bugs_and_glitches.md)
  	push hl
  	push de
  	ld a, [wEnemyMonSpecies]
--	; dec a
 +	dec a
  	rlca
  	rlca
@@ -1256,12 +1252,13 @@
 
 ### Glacier Badge may not boost Special Defense depending on the value of Special Attack
 
-As Pryce's dialog ("That BADGE will raise the SPECIAL stats of POKéMON.") implies, Glacier Badge is intended to boost both Special Attack and Special Defense. However, due to BoostStat overwriting `a` when boosting Special Attack, the Special Defense boost will not happen if the unboosted Special Attack stat is either 0–205 or 433–660.
+Pryce's dialog ("That BADGE will raise the SPECIAL stats of POKéMON.") implies that Glacier Badge is intended to boost both Special Attack and Special Defense, but the Special Defense boost will not happen unless the unboosted Special Attack stat is 206–432, or 661 or above.
 
 **Fix:** Edit `BadgeStatBoosts.CheckBadge` in [engine/battle/core.asm](https://github.com/pret/pokecrystal/blob/master/engine/battle/core.asm):
 
 ```diff
  .CheckBadge:
+-; BUG: Glacier Badge may not boost Special Defense depending on the value of Special Attack (see docs/bugs_and_glitches.md)
  	ld a, b
  	srl b
 +	push af
@@ -1273,9 +1270,6 @@
  	srl b
  	dec c
  	jr nz, .CheckBadge
- ; Check GlacierBadge again for Special Defense.
--; This check is buggy because it assumes that a is set by the "ld a, b" in the above loop,
--; but it can actually be overwritten by the call to BoostStat.
  	srl a
  	call c, BoostStat
  	ret
@@ -1289,10 +1283,9 @@
 **Fix:** Edit `AI_Smart_MeanLook` in [engine/battle/ai/scoring.asm](https://github.com/pret/pokecrystal/blob/master/engine/battle/ai/scoring.asm):
 
 ```diff
--; 80% chance to greatly encourage this move if the enemy is badly poisoned (buggy).
--; Should check wPlayerSubStatus5 instead.
+ ; 80% chance to greatly encourage this move if the enemy is badly poisoned.
+-; BUG: "Smart" AI encourages Mean Look if its own Pokémon is badly poisoned (see docs/bugs_and_glitches.md)
 -	ld a, [wEnemySubStatus5]
-+; 80% chance to greatly encourage this move if the player is badly poisoned
 +	ld a, [wPlayerSubStatus5]
  	bit SUBSTATUS_TOXIC, a
  	jr nz, .asm_38e26
@@ -1305,9 +1298,10 @@
 
 ```diff
  AI_Smart_Conversion2:
+-; BUG: "Smart" AI discourages Conversion2 after the first turn (see docs/bugs_and_glitches.md)
  	ld a, [wLastPlayerMove]
  	and a
--	jr nz, .discourage ; should be jr z
+-	jr nz, .discourage
 +	jr z, .discourage
 ```
 
@@ -1317,7 +1311,8 @@
 **Fix:** Edit `SunnyDayMoves` in [data/battle/ai/sunny_day_moves.asm](https://github.com/pret/pokecrystal/blob/master/data/battle/ai/sunny_day_moves.asm):
 
 ```diff
-SunnyDayMoves:
+ SunnyDayMoves:
+-; BUG: "Smart" AI does not encourage Solar Beam, Flame Wheel, or Moonlight during Sunny Day (see docs/bugs_and_glitches.md)
  	db FIRE_PUNCH
  	db EMBER
  	db FLAMETHROWER
@@ -1339,6 +1334,7 @@
 
 ```diff
  .FutureSight:
+-; BUG: AI does not discourage Future Sight when it's already been used (see docs/bugs_and_glitches.md)
 -	ld a, [wEnemyScreens]
 -	bit 5, a
 +	ld a, [wEnemyFutureSightCount]
@@ -1362,13 +1358,9 @@
 +.get_type
 +	ld a, BATTLE_VARS_MOVE_TYPE
 +	call GetBattleVar ; preserves hl, de, and bc
+ 	; fallthrough
  CheckTypeMatchup:
--; There is an incorrect assumption about this function made in the AI related code: when
--; the AI calls CheckTypeMatchup (not BattleCheckTypeMatchup), it assumes that placing the
--; offensive type in a will make this function do the right thing. Since a is overwritten,
--; this assumption is incorrect. A simple fix would be to load the move type for the
--; current move into a in BattleCheckTypeMatchup, before falling through, which is
--; consistent with how the rest of the code assumes this code works like.
+-; BUG: AI makes a false assumption about CheckTypeMatchup (see docs/bugs_and_glitches.md)
  	push hl
  	push de
  	push bc
@@ -1387,6 +1379,7 @@
 
 ```diff
  AI_HealStatus:
+-; BUG: AI use of Full Heal or Full Restore does not cure Nightmare status (see docs/bugs_and_glitches.md)
  	ld a, [wCurOTMon]
  	ld hl, wOTPartyMon1Status
  	ld bc, PARTYMON_STRUCT_LENGTH
@@ -1394,13 +1387,11 @@
  	xor a
  	ld [hl], a
  	ld [wEnemyMonStatus], a
--	; Bug: this should reset SUBSTATUS_NIGHTMARE
--	; Uncomment the 2 lines below to fix
--	; ld hl, wEnemySubStatus1
--	; res SUBSTATUS_NIGHTMARE, [hl]
 +	ld hl, wEnemySubStatus1
 +	res SUBSTATUS_NIGHTMARE, [hl]
- 	...
+ 	ld hl, wEnemySubStatus5
+ 	res SUBSTATUS_TOXIC, [hl]
+ 	ret
 ```
 
 
@@ -1410,6 +1401,7 @@
 
 ```diff
  EnemyUsedFullRestore:
+-; BUG: AI use of Full Heal does not cure confusion status (see docs/bugs_and_glitches.md)
  	call AI_HealStatus
  	ld a, FULL_RESTORE
  	ld [wCurEnemyItem], a
@@ -1417,10 +1409,12 @@
 -	res SUBSTATUS_CONFUSED, [hl]
 - 	xor a
 - 	ld [wEnemyConfuseCount], a
+ 	; fallthrough
 ```
 
 ```diff
  AI_HealStatus:
+ ; BUG: AI use of Full Heal or Full Restore does not cure Nightmare status (see docs/bugs_and_glitches.md)
  	ld a, [wCurOTMon]
  	ld hl, wOTPartyMon1Status
  	ld bc, PARTYMON_STRUCT_LENGTH
@@ -1429,14 +1423,6 @@
  	ld [hl], a
  	ld [wEnemyMonStatus], a
 +	ld [wEnemyConfuseCount], a
-	; Bug: this should reset SUBSTATUS_NIGHTMARE
-	; Uncomment the 2 lines below to fix
-	; ld hl, wEnemySubStatus1
-	; res SUBSTATUS_NIGHTMARE, [hl]
--	; Bug: this should reset SUBSTATUS_CONFUSED
--	; Uncomment the 2 lines below to fix
--	; ld hl, wEnemySubStatus3
--	; res SUBSTATUS_CONFUSED, [hl]
 +	ld hl, wEnemySubStatus3
 +	res SUBSTATUS_CONFUSED, [hl]
  	ld hl, wEnemySubStatus5
@@ -1451,6 +1437,8 @@
 
 ```diff
  .loop_enemy
+-; BUG: Wild Pokémon can always Teleport regardless of level difference (see docs/bugs_and_glitches.md)
++; If a random number >= player level / 4, Teleport will succeed
  	call BattleRandom
  	cp c
  	jr nc, .loop_enemy
@@ -1457,9 +1445,6 @@
  	; b = player level / 4
  	srl b
  	srl b
--	; This should be "jr c, .failed"
--	; As written, it makes enemy use of Teleport always succeed if able
-+	; If the random number >= player level / 4, Teleport will succeed
  	cp b
 -	jr nc, .run_away
 +	jr c, .failed
@@ -1475,6 +1460,7 @@
 ```diff
  	dn 13, 13, 13, 13 ; RIVAL1
  	...
+-; BUG: RIVAL2 has lower DVs than RIVAL1 (see docs/bugs_and_glitches.md)
 -	dn  9,  8,  8,  8 ; RIVAL2
 +	dn 13, 13, 13, 13 ; RIVAL2
 ```
@@ -1485,13 +1471,10 @@
 **Fix:** Edit `PokeBallEffect` in [engine/items/item_effects.asm](https://github.com/pret/pokecrystal/blob/master/engine/items/item_effects.asm):
 
 ```diff
--	; BUG: farcall overwrites a, and GetItemHeldEffect takes b anyway.
--	; This is probably the reason the HELD_CATCH_CHANCE effect is never used.
--	; Uncomment the line below to fix.
+-; BUG: HELD_CATCH_CHANCE has no effect (see docs/bugs_and_glitches.md)
  	ld d, a
  	push de
  	ld a, [wBattleMonItem]
--	; ld b, a
 +	ld b, a
  	farcall GetItemHeldEffect
  	ld a, b
@@ -1515,6 +1498,7 @@
 **Fix:** Edit `Credits` in [engine/movie/credits.asm](https://github.com/pret/pokecrystal/blob/master/engine/movie/credits.asm):
 
 ```diff
+-; BUG: Credits sequence changes move selection menu behavior (see docs/bugs_and_glitches.md)
  	ldh a, [hVBlank]
  	push af
  	ld a, $5
@@ -1521,7 +1505,7 @@
  	ldh [hVBlank], a
 +	ldh a, [hInMenu]
 +	push af
- 	ld a, $1
+ 	ld a, TRUE
  	ldh [hInMenu], a
 
  	...
@@ -1571,12 +1555,10 @@
 
 ```diff
  	; Set hl to the address of the current metatile data ([wTilesetBlocksAddress] + (a) tiles).
--	; This is buggy; it wraps around past 128 blocks.
--	; To fix, uncomment the line below.
--	add a ; Comment or delete this line to fix the above bug.
+-; BUG: LoadMetatiles wraps around past 128 blocks (see docs/bugs_and_glitches.md)
+-	add a
  	ld l, a
  	ld h, 0
--	; add hl, hl
 +	add hl, hl
  	add hl, hl
  	add hl, hl
@@ -1600,6 +1582,7 @@
 
 ```diff
  UsedSurfScript:
+-; BUG: Surfing directly across a map connection does not load the new map (see docs/bugs_and_glitches.md)
  	writetext UsedSurfText ; "used SURF!"
  	waitbutton
  	closetext
@@ -1665,10 +1648,10 @@
 **Fix:** Edit `CanObjectMoveInDirection` in [engine/overworld/npc_movement.asm](https://github.com/pret/pokecrystal/blob/master/engine/overworld/npc_movement.asm):
 
 ```diff
+-; BUG: Swimming NPCs aren't limited by their movement radius (see docs/bugs_and_glitches.md)
  	ld hl, OBJECT_FLAGS1
  	add hl, bc
- 	bit NOCLIP_TILES_F, [hl] ; lost, uncomment next line to fix
--	; jr nz, .noclip_tiles
+ 	bit NOCLIP_TILES_F, [hl]
 +	jr nz, .noclip_tiles
 ```
 
@@ -1675,7 +1658,7 @@
 
 ### Pokémon deposited in the Day-Care might lose experience
 
-This happens because when a Pokémon is withdrawn from the Day-Care, its Exp. Points are reset to the minimum required for its level. This means that if it hasn't gained any levels, it may lose experience.
+When a Pokémon is withdrawn from the Day-Care, its Exp. Points are reset to the minimum required for its level. This means that if it hasn't gained any levels, it may lose experience.
 
 **Fix**: Edit `RetrieveBreedmon` in [engine/pokemon/move_mon.asm](https://github.com/pret/pokecrystal/blob/master/engine/pokemon/move_mon.asm):
 
@@ -1683,7 +1666,7 @@
  RetrieveBreedmon:
 
  	...
-
+-; BUG: Pokémon deposited in the Day-Care might lose experience (see docs/bugs_and_glitches.md)
  	ld a, [wPartyCount]
  	dec a
  	ld [wCurPartyMon], a
@@ -1690,7 +1673,6 @@
  	farcall HealPartyMon
 -	ld a, [wCurPartyLevel]
 -	ld d, a
-+	; Check if there's an exp overflow
 +	ld d, MAX_LEVEL
  	callfar CalcExpAtLevel
  	pop bc
@@ -1770,12 +1752,11 @@
 
 ### A hatching Unown egg would not show the right letter
 
-This happens because both `GetEggFrontpic` and `GetHatchlingFrontpic` use `wBattleMonDVs`, but that's not initialized. They should use the current party mon's DVs instead.
-
 **Fix:** Edit both functions in [engine/pokemon/breeding.asm](https://github.com/pret/pokecrystal/blob/master/engine/pokemon/breeding.asm):
 
 ```diff
  GetEggFrontpic:
+-; BUG: A hatching Unown egg would not show the right letter (see docs/bugs_and_glitches.md)
  	push de
  	ld [wCurPartySpecies], a
  	ld [wCurSpecies], a
@@ -1809,6 +1790,7 @@
 
 ```diff
  .room_in_party
+-; BUG: Using a Park Ball in non-Contest battles has a corrupt animation (see docs/bugs_and_glitches.md)
  	xor a
  	ld [wWildMon], a
 -	ld a, [wCurItem]
@@ -1837,8 +1819,7 @@
  StartTrainerBattle_DetermineWhichAnimation:
  ; The screen flashes a different number of times depending on the level of
  ; your lead Pokemon relative to the opponent's.
--; BUG: wBattleMonLevel and wEnemyMonLevel are not set at this point, so whatever
--; values happen to be there will determine the animation.
+-; BUG: Battle transitions fail to account for enemy's level (see docs/bugs_and_glitches.md)
 +	ld a, [wOtherTrainerClass]
 +	and a
 +	jr z, .wild
@@ -2013,12 +1994,13 @@
 
 ```diff
  .okay
+-; BUG: Slot machine payout sound effects cut each other off (see docs/bugs_and_glitches.md)
  	ld [hl], e
  	dec hl
  	ld [hl], d
  	ld a, [wSlotsDelay]
  	and $7
--	ret z ; ret nz would be more appropriate
+-	ret z
 +	ret nz
  	ld de, SFX_GET_COIN_FROM_SLOTS
  	call PlaySFX
@@ -2031,6 +2013,7 @@
 **Fix:** Edit `PlayBattleMusic` in [engine/battle/start_battle.asm](https://github.com/pret/pokecrystal/blob/master/engine/battle/start_battle.asm):
 
 ```diff
+-; BUG: Team Rocket battle music is not used for Executives or Scientists (see docs/bugs_and_glitches.md)
  	ld de, MUSIC_ROCKET_BATTLE
  	cp GRUNTM
  	jr z, .done
@@ -2047,18 +2030,15 @@
 
 ### No bump noise if standing on tile `$3E`
 
+If `[wWalkingDirection]` is `STANDING` (`$FF`), this will check `[.EdgeWarps + $ff]`, which happens to be `$3E`.
+
 **Fix:** Edit `DoPlayerMovement.CheckWarp` in [engine/overworld/player_movement.asm](https://github.com/pret/pokecrystal/blob/master/engine/overworld/player_movement.asm):
 
 ```diff
  .CheckWarp:
--; Bug: Since no case is made for STANDING here, it will check
--; [.EdgeWarps + $ff]. This resolves to $3e.
--; This causes wWalkingIntoEdgeWarp to be nonzero when standing on tile $3e,
--; making bumps silent.
--
+-; BUG: No bump noise if standing on tile $3E (see docs/bugs_and_glitches.md)
+
  	ld a, [wWalkingDirection]
--	; cp STANDING
--	; jr z, .not_warp
 +	cp STANDING
 +	jr z, .not_warp
  	ld e, a
@@ -2072,7 +2052,6 @@
  	ld a, TRUE
  	ld [wWalkingIntoEdgeWarp], a
  	ld a, [wWalkingDirection]
--	; This is in the wrong place.
 -	cp STANDING
 -	jr z, .not_warp
 ```
@@ -2088,6 +2067,7 @@
 
 ```diff
  .Cry:
+-; BUG: Playing Entei's Pokédex cry can distort Raikou's and Suicune's (see docs/bugs_and_glitches.md)
 -	call Pokedex_GetSelectedMon
 -	ld a, [wTempSpecies]
 -	call GetCryIndex
@@ -2111,6 +2091,7 @@
 
 ```diff
  _BoostedExpPointsText::
+-; BUG: Five-digit experience gain is printed incorrectly (see docs/bugs_and_glitches.md)
  	text_start
  	line "a boosted"
  	cont "@"
@@ -2120,6 +2101,7 @@
  	prompt
 
  _ExpPointsText::
+-; BUG: Five-digit experience gain is printed incorrectly (see docs/bugs_and_glitches.md)
  	text_start
  	line "@"
 -	text_decimal wStringBuffer2, 2, 4
@@ -2135,6 +2117,7 @@
 
 ```diff
  .DetermineCompatibility:
+-; BUG: Only the first three evolution entries can have Stone compatibility reported correctly (see docs/bugs_and_glitches.md)
  	ld de, wStringBuffer1
  	ld a, BANK(EvosAttacksPointers)
  	ld bc, 2
@@ -2159,6 +2142,7 @@
 
 ```diff
  .loop2
+-; BUG: EVOLVE_STAT can break Stone compatibility reporting (see docs/bugs_and_glitches.md)
  	ld a, [hli]
  	and a
  	jr z, .nope
@@ -2180,8 +2164,9 @@
 **Fix:** Edit `_HallOfFamePC.DisplayMonAndStrings` in [engine/events/halloffame.asm](https://github.com/pret/pokecrystal/blob/master/engine/events/halloffame.asm):
 
 ```diff
+-; BUG: A "HOF Master!" title for 200-Time Famers is defined but inaccessible (see docs/bugs_and_glitches.md)
  	ld a, [wHallOfFameTempWinCount]
--	cp HOF_MASTER_COUNT + 1 ; should be HOF_MASTER_COUNT
+-	cp HOF_MASTER_COUNT + 1
 +	cp HOF_MASTER_COUNT
  	jr c, .print_num_hof
  	ld de, .HOFMaster
@@ -2199,8 +2184,10 @@
 
 ([Video](https://www.youtube.com/watch?v=8BvBjqxmyOk))
 
-**Fix:** Edit `DragonsDen1F_MapScripts` in [maps/DragonsDen1F.asm](https://github.com/pret/pokecrystal/blob/master/maps/DragonsDen1F.asm):
+**Fix:**
 
+Edit `DragonsDen1F_MapScripts` in [maps/DragonsDen1F.asm](https://github.com/pret/pokecrystal/blob/master/maps/DragonsDen1F.asm):
+
 ```diff
  	def_callbacks
 +	callback MAPCALLBACK_NEWMAP, .UnsetClairScene
@@ -2210,19 +2197,21 @@
 +	endcallback
 ```
 
+And edit [maps/DragonsDenB1F.asm](https://github.com/pret/pokecrystal/blob/master/maps/DragonsDenB1F.asm):
 
+```diff
+ DragonsDenB1F_ClairScene:
+-; BUG: Clair can give TM24 Dragonbreath twice (see docs/bugs_and_glitches.md)
+```
+
+
 ### Daisy's grooming doesn't always increase happiness
 
+Subtracting `$FF` from `$FF` fails to set the carry flag, which results in a 0.4% chance that Daisy's grooming will not affect your Pokémon's happiness.
+
 This is a bug with `HaircutOrGrooming` in [engine/events/haircut.asm](https://github.com/pret/pokecrystal/blob/master/engine/events/haircut.asm):
 
 ```asm
-; Bug: Subtracting $ff from $ff fails to set c.
-; This can result in overflow into the next data array.
-; In the case of getting a grooming from Daisy, we bleed
-; into CopyPokemonName_Buffer1_Buffer3, which passes
-; $d0 to ChangeHappiness and returns $73 to the script.
-; The end result is that there is a 0.4% chance your
-; Pokemon's happiness will not change at all.
 .loop
 	sub [hl]
 	jr c, .ok
@@ -2254,6 +2243,7 @@
 
 ```diff
  HappinessData_DaisysGrooming:
+-; BUG: Daisy's grooming doesn't always increase happiness (see docs/bugs_and_glitches.md)
 -	db -1,             2, HAPPINESS_GROOMING ; 99.6% chance
 +	db 50 percent,     2, HAPPINESS_GROOMING ; 50% chance
 +	db -1,             2, HAPPINESS_GROOMING ; 50% chance
@@ -2262,23 +2252,13 @@
 
 ### Magikarp in Lake of Rage are shorter, not longer
 
+`cp HIGH(1024)` should be `cp 3`, since 1024 mm = 3'4", but `HIGH(1024)` = 4.
+
 **Fix:** Edit `LoadEnemyMon.CheckMagikarpArea` in [engine/battle/core.asm](https://github.com/pret/pokecrystal/blob/master/engine/battle/core.asm):
 
 ```diff
  .CheckMagikarpArea:
--; The "jr z" checks are supposed to be "jr nz".
--
--; Instead, all maps in GROUP_LAKE_OF_RAGE (Mahogany area)
--; and Routes 20 and 44 are treated as Lake of Rage.
--
--; This also means Lake of Rage Magikarp can be smaller than ones
--; caught elsewhere rather than the other way around.
--
--; Intended behavior enforces a minimum size at Lake of Rage.
--; The real behavior prevents a minimum size in the Lake of Rage area.
--
--; Moreover, due to the check not being translated to feet+inches, all Magikarp
--; smaller than 4'0" may be caught by the filter, a lot more than intended.
+-; BUG: Magikarp in Lake of Rage are shorter, not longer (see docs/bugs_and_glitches.md)
  	ld a, [wMapGroup]
  	cp GROUP_LAKE_OF_RAGE
 -	jr z, .Happiness
@@ -2287,15 +2267,29 @@
  	cp MAP_LAKE_OF_RAGE
 -	jr z, .Happiness
 +	jr nz, .Happiness
+ ; 40% chance of not flooring
+ 	call Random
+ 	cp 39 percent + 1
+ 	jr c, .Happiness
+ ; Try again if length < 1024 mm (i.e. if HIGH(length) < 3 feet)
+ 	ld a, [wMagikarpLength]
+-	cp HIGH(1024)
++	cp 3
+ 	jr c, .GenerateDVs ; try again
 ```
 
 
 ### Magikarp length limits have a unit conversion error
 
+- `cp HIGH(1536)` should be `cp 5`, since 1536 mm = 5'0", but `HIGH(1536)` = 6.
+- `cp LOW(1616)` should be `cp 4`, since 1616 mm = 5'4", but `LOW(1616)` = 80.
+- `cp LOW(1600)` should be `cp 3`, since 1600 mm = 5'3", but `LOW(1600)` = 64.
+
 **Fix:** Edit `LoadEnemyMon.CheckMagikarpArea` in [engine/battle/core.asm](https://github.com/pret/pokecrystal/blob/master/engine/battle/core.asm):
 
 ```diff
  ; Get Magikarp's length
+-; BUG: Magikarp length limits have a unit conversion error (see docs/bugs_and_glitches.md)
  	ld de, wEnemyMonDVs
  	ld bc, wPlayerID
  	callfar CalcMagikarpLength
@@ -2302,7 +2296,7 @@
 
  ; No reason to keep going if length > 1536 mm (i.e. if HIGH(length) > 6 feet)
  	ld a, [wMagikarpLength]
--	cp HIGH(1536) ; should be "cp 5", since 1536 mm = 5'0", but HIGH(1536) = 6
+-	cp HIGH(1536)
 +	cp 5
  	jr nz, .CheckMagikarpArea
 
@@ -2312,7 +2306,7 @@
  	jr c, .CheckMagikarpArea
  ; Try again if length >= 1616 mm (i.e. if LOW(length) >= 4 inches)
  	ld a, [wMagikarpLength + 1]
--	cp LOW(1616) ; should be "cp 4", since 1616 mm = 5'4", but LOW(1616) = 80
+-	cp LOW(1616)
 +	cp 4
  	jr nc, .GenerateDVs
 
@@ -2322,7 +2316,7 @@
  	jr c, .CheckMagikarpArea
  ; Try again if length >= 1600 mm (i.e. if LOW(length) >= 3 inches)
  	ld a, [wMagikarpLength + 1]
--	cp LOW(1600) ; should be "cp 3", since 1600 mm = 5'3", but LOW(1600) = 64
+-	cp LOW(1600)
 +	cp 3
  	jr nc, .GenerateDVs
 ```
@@ -2336,12 +2330,11 @@
 
 ```diff
  .BCLessThanDE:
--; Intention: Return bc < de.
--; Reality: Return b < d.
+-; BUG: Magikarp lengths can be miscalculated (see docs/bugs_and_glitches.md)
  	ld a, b
  	cp d
  	ret c
--	ret nc ; whoops
+-	ret nc
  	ld a, c
  	cp e
  	ret
@@ -2357,13 +2350,12 @@
 **Fix:** Edit `CheckOwnMon` in [engine/pokemon/search_owned.asm](https://github.com/pret/pokecrystal/blob/master/engine/pokemon/search_owned.asm):
 
 ```diff
- ; check OT
--; This only checks five characters, which is fine for the Japanese version,
--; but in the English version the player name is 7 characters, so this is wrong.
+ 	; check OT
 
  	ld hl, wPlayerName
 
--rept NAME_LENGTH_JAPANESE - 2 ; should be PLAYER_NAME_LENGTH - 2
+-; BUG: CheckOwnMon only checks the first five letters of OT names (see docs/bugs_and_glitches.md)
+-rept NAME_LENGTH_JAPANESE - 2
 +rept PLAYER_NAME_LENGTH - 2
  	ld a, [de]
  	cp [hl]
@@ -2391,10 +2383,12 @@
 ```diff
  	; If there are no monsters in the party,
  	; the player must not own any yet.
+-; BUG: CheckOwnMon does not check the Day-Care (see docs/bugs_and_glitches.md)
  	ld a, [wPartyCount]
  	and a
  	ret z
-+
+
+-; BUG: CheckOwnMon does not check the Day-Care (see docs/bugs_and_glitches.md)
 +	ld hl, wBreedMon1Species
 +	ld bc, wBreedMon1OT
 +	call CheckOwnMon
@@ -2414,6 +2408,7 @@
 **Fix:** Edit `PhoneCall.CallerTextboxWithName` in [engine/phone/phone.asm](https://github.com/pret/pokecrystal/blob/master/engine/phone/phone.asm):
 
 ```diff
+-; BUG: The unused phonecall script command may crash (see docs/bugs_and_glitches.md)
 -	ld a, [wPhoneScriptBank]
 -	ld b, a
  	ld a, [wPhoneCaller]
@@ -2426,7 +2421,7 @@
  	ret
 ```
 
-You can also delete the now-unused `BrokenPlaceFarString` routine.
+You can also delete the now-unused `BrokenPlaceFarString` routine in the same file.
 
 
 ## Internal engine routines
@@ -2436,7 +2431,7 @@
 
 ([Video 1](https://www.youtube.com/watch?v=ukqtK0l6bu0), [Video 2](https://www.youtube.com/watch?v=c2zHd1BPtvc))
 
-This does not have a simple and accurate fix. It would involve redesigning parts of the save system for Pokémon boxes.
+This allows Pokémon to be duplicated, among other effects. It does not have a simple and accurate fix. A fix would involve redesigning parts of the save system for Pokémon boxes.
 
 
 ### `ScriptCall` can overflow `wScriptStack` and crash
@@ -2445,11 +2440,7 @@
 
 ```diff
  ScriptCall:
--; Bug: The script stack has a capacity of 5 scripts, yet there is
--; nothing to stop you from pushing a sixth script.  The high part
--; of the script address can then be overwritten by modifications
--; to wScriptDelay, causing the script to return to the rst/interrupt
--; space.
+-; BUG: ScriptCall can overflow wScriptStack and crash (see docs/bugs_and_glitches.md)
 -
 +	ld hl, wScriptStackSize
 +	ld a, [hl]
@@ -2488,8 +2479,7 @@
 
 ```diff
  LoadSpriteGFX:
--; Bug: b is not preserved, so it's useless as a next count.
--; Uncomment the lines below to fix.
+-; BUG: LoadSpriteGFX does not limit the capacity of UsedSprites (see docs/bugs_and_glitches.md)
 -
  	ld hl, wUsedSprites
  	ld b, SPRITE_GFX_LIST_CAPACITY
@@ -2508,10 +2498,8 @@
  	ret
 
  .LoadSprite:
--	; push bc
 +	push bc
  	call GetSprite
--	; pop bc
 +	pop bc
  	ld a, l
  	ret
@@ -2524,15 +2512,15 @@
 
 ```diff
  .ok
+-; BUG: ChooseWildEncounter doesn't really validate the wild Pokemon species (see docs/bugs_and_glitches.md)
  	ld a, b
  	ld [wCurPartyLevel], a
  	ld b, [hl]
--	; ld a, b
 +	ld a, b
  	call ValidateTempWildMonSpecies
  	jr c, .nowildbattle
 
--	ld a, b ; This is in the wrong place.
+-	ld a, b
  	cp UNOWN
  	jr nz, .done
 ```
@@ -2540,13 +2528,15 @@
 
 ### `TryObjectEvent` arbitrary code execution
 
+If `IsInArray` returns `nc`, data at `bc` will be executed as code.
+
 **Fix:** Edit `TryObjectEvent` in [engine/overworld/events.asm](https://github.com/pret/pokecrystal/blob/master/engine/overworld/events.asm):
 
 ```diff
--; Bug: If IsInArray returns nc, data at bc will be executed as code.
+-; BUG: TryObjectEvent arbitrary code execution (see docs/bugs_and_glitches.md)
  	push bc
  	ld de, 3
- 	ld hl, .pointers
+ 	ld hl, ObjectEventTypeArray
  	call IsInArray
 -	jr nc, .nope
  	pop bc
@@ -2559,7 +2549,6 @@
  	jp hl
 
  .nope
--	; pop bc
  	xor a
  	ret
 ```
@@ -2572,20 +2561,18 @@
 ```diff
 -; get NUM_OBJECTS - [wCurMapObjectEventCount]
 +; get NUM_OBJECTS - [wCurMapObjectEventCount] - 1
+-; BUG: ReadObjectEvents overflows into wObjectMasks (see docs/bugs_and_glitches.md)
  	ld a, [wCurMapObjectEventCount]
  	ld c, a
--	ld a, NUM_OBJECTS ; - 1
+-	ld a, NUM_OBJECTS
 +	ld a, NUM_OBJECTS - 1
  	sub c
  	jr z, .skip
--	; jr c, .skip
 +	jr c, .skip
 
  	; could have done "inc hl" instead
  	ld bc, 1
  	add hl, bc
--; Fill the remaining sprite IDs and y coords with 0 and -1, respectively.
--; Bleeds into wObjectMasks due to a bug.  Uncomment the above code to fix.
  	ld bc, MAPOBJECT_LENGTH
  .loop
  	ld [hl],  0
@@ -2606,6 +2593,7 @@
  ClearWRAM::
  ; Wipe swappable WRAM banks (1-7)
  ; Assumes CGB or AGB
+-; BUG: ClearWRAM only clears WRAM bank 1 (see docs/bugs_and_glitches.md)
 
  	ld a, 1
  .bank_loop
@@ -2618,7 +2606,7 @@
  	pop af
  	inc a
  	cp 8
--	jr nc, .bank_loop ; Should be jr c
+-	jr nc, .bank_loop
 +	jr c, .bank_loop
  	ret
 ```
@@ -2630,9 +2618,9 @@
 
 ```diff
  BattleAnimCmd_ClearObjs:
--; BUG: This function only clears the first 6⅔ objects
+-; BUG: BattleAnimCmd only clears the first 6⅔ objects (see docs/bugs_and_glitches.md)
  	ld hl, wActiveAnimObjects
--	ld a, $a0 ; should be NUM_ANIM_OBJECTS * BATTLEANIMSTRUCT_LENGTH
+-	ld a, $a0
 +	ld a, NUM_ANIM_OBJECTS * BATTLEANIMSTRUCT_LENGTH
  .loop
  	ld [hl], 0
--- a/engine/battle/ai/items.asm
+++ b/engine/battle/ai/items.asm
@@ -552,6 +552,7 @@
 	jr FullRestoreContinue
 
 EnemyUsedFullRestore:
+; BUG: AI use of Full Heal does not cure confusion status (see docs/bugs_and_glitches.md)
 	call AI_HealStatus
 	ld a, FULL_RESTORE
 	ld [wCurEnemyItem], a
@@ -559,6 +560,7 @@
 	res SUBSTATUS_CONFUSED, [hl]
 	xor a
 	ld [wEnemyConfuseCount], a
+	; fallthrough
 
 FullRestoreContinue:
 	ld de, wCurHPAnimOldHP
@@ -725,6 +727,7 @@
 	jp PrintText_UsedItemOn_AND_AIUpdateHUD
 
 AI_HealStatus:
+; BUG: AI use of Full Heal or Full Restore does not cure Nightmare status (see docs/bugs_and_glitches.md)
 	ld a, [wCurOTMon]
 	ld hl, wOTPartyMon1Status
 	ld bc, PARTYMON_STRUCT_LENGTH
@@ -732,14 +735,6 @@
 	xor a
 	ld [hl], a
 	ld [wEnemyMonStatus], a
-	; Bug: this should reset SUBSTATUS_NIGHTMARE
-	; Uncomment the 2 lines below to fix
-	; ld hl, wEnemySubStatus1
-	; res SUBSTATUS_NIGHTMARE, [hl]
-	; Bug: this should reset SUBSTATUS_CONFUSED
-	; Uncomment the 2 lines below to fix
-	; ld hl, wEnemySubStatus3
-	; res SUBSTATUS_CONFUSED, [hl]
 	ld hl, wEnemySubStatus5
 	res SUBSTATUS_TOXIC, [hl]
 	ret
--- a/engine/battle/ai/redundant.asm
+++ b/engine/battle/ai/redundant.asm
@@ -176,6 +176,7 @@
 	ret
 
 .FutureSight:
+; BUG: AI does not discourage Future Sight when it's already been used (see docs/bugs_and_glitches.md)
 	ld a, [wEnemyScreens]
 	bit 5, a
 	ret
--- a/engine/battle/ai/scoring.asm
+++ b/engine/battle/ai/scoring.asm
@@ -1665,9 +1665,10 @@
 	ret
 
 AI_Smart_Conversion2:
+; BUG: "Smart" AI discourages Conversion2 after the first turn (see docs/bugs_and_glitches.md)
 	ld a, [wLastPlayerMove]
 	and a
-	jr nz, .discourage ; should be jr z
+	jr nz, .discourage
 
 	push hl
 	dec a
@@ -1743,8 +1744,8 @@
 	pop hl
 	jp z, AIDiscourageMove
 
-; 80% chance to greatly encourage this move if the enemy is badly poisoned (buggy).
-; Should check wPlayerSubStatus5 instead.
+; 80% chance to greatly encourage this move if the enemy is badly poisoned.
+; BUG: "Smart" AI encourages Mean Look if its own Pokémon is badly poisoned (see docs/bugs_and_glitches.md)
 	ld a, [wEnemySubStatus5]
 	bit SUBSTATUS_TOXIC, a
 	jr nz, .encourage
--- a/engine/battle/anim_hp_bar.asm
+++ b/engine/battle/anim_hp_bar.asm
@@ -179,16 +179,12 @@
 	ld c, a
 	ld a, [hli]
 	ld b, a
-	; This routine is buggy. The result from ComputeHPBarPixels is stored
-	; in e. However, the pop de opcode deletes this result before it is even
-	; used. The game then proceeds as though it never deleted that output.
-	; To fix, uncomment the line below.
+; BUG: HP bar animation is slow for high HP (see docs/bugs_and_glitches.md)
 	call ComputeHPBarPixels
-	; ld a, e
 	pop bc
 	pop de
 	pop hl
-	ld a, e ; Comment or delete this line to fix the above bug.
+	ld a, e
 	ld hl, wCurHPBarPixels
 	cp [hl]
 	jr z, .loop
@@ -373,10 +369,8 @@
 	call AddNTimes
 
 	ld b, 0
-; This routine is buggy. If [wCurHPAnimMaxHP] * [wCurHPBarPixels] is
-; divisible by HP_BAR_LENGTH_PX, the loop runs one extra time.
-; To fix, uncomment the line below.
 .loop
+; BUG: HP bar animation off-by-one error for low HP (see docs/bugs_and_glitches.md)
 	ld a, l
 	sub HP_BAR_LENGTH_PX
 	ld l, a
@@ -383,7 +377,6 @@
 	ld a, h
 	sbc $0
 	ld h, a
-	; jr z, .done
 	jr c, .done
 	inc b
 	jr .loop
--- a/engine/battle/battle_transition.asm
+++ b/engine/battle/battle_transition.asm
@@ -214,8 +214,7 @@
 StartTrainerBattle_DetermineWhichAnimation:
 ; The screen flashes a different number of times depending on the level of
 ; your lead Pokemon relative to the opponent's.
-; BUG: wBattleMonLevel and wEnemyMonLevel are not set at this point, so whatever
-; values happen to be there will determine the animation.
+; BUG: Battle transitions fail to account for enemy's level (see docs/bugs_and_glitches.md)
 	ld de, 0
 	ld a, [wBattleMonLevel]
 	add 3
--- a/engine/battle/core.asm
+++ b/engine/battle/core.asm
@@ -295,6 +295,7 @@
 	jp HandleEncore
 
 CheckFaint_PlayerThenEnemy:
+; BUG: Perish Song and Spikes can leave a Pokemon with 0 HP and not faint (see docs/bugs_and_glitches.md)
 	call HasPlayerFainted
 	jr nz, .PlayerNotFainted
 	call HandlePlayerMonFaint
@@ -319,6 +320,7 @@
 	ret
 
 CheckFaint_EnemyThenPlayer:
+; BUG: Perish Song and Spikes can leave a Pokemon with 0 HP and not faint (see docs/bugs_and_glitches.md)
 	call HasEnemyFainted
 	jr nz, .EnemyNotFainted
 	call HandleEnemyMonFaint
@@ -387,6 +389,7 @@
 	call GetPartyLocation
 	xor a
 	ld [hl], a
+; BUG: Berserk Gene's confusion lasts for 256 turns or the previous Pokémon's confusion count (see docs/bugs_and_glitches.md)
 	ld a, BATTLE_VARS_SUBSTATUS3
 	call GetBattleVarAddr
 	push af
@@ -4186,6 +4189,7 @@
 	or [hl]
 	jr nz, .done
 
+; BUG: A Pokémon that fainted from Pursuit will have its old status condition when revived (see docs/bugs_and_glitches.md)
 	ld a, $f0
 	ld [wCryTracks], a
 	ld a, [wBattleMonSpecies]
@@ -5759,8 +5763,8 @@
 	jr .loop
 
 .done
-	; Bug: this will result in a move with PP Up confusing the game.
-	and a ; should be "and PP_MASK"
+; BUG: A Disabled but PP Up–enhanced move may not trigger Struggle (see docs/bugs_and_glitches.md)
+	and a
 	ret nz
 
 .force_struggle
@@ -6159,6 +6163,7 @@
 	jr nz, .Happiness
 
 ; Get Magikarp's length
+; BUG: Magikarp length limits have a unit conversion error (see docs/bugs_and_glitches.md)
 	ld de, wEnemyMonDVs
 	ld bc, wPlayerID
 	callfar CalcMagikarpLength
@@ -6165,7 +6170,7 @@
 
 ; No reason to keep going if length > 1536 mm (i.e. if HIGH(length) > 6 feet)
 	ld a, [wMagikarpLength]
-	cp HIGH(1536) ; should be "cp 5", since 1536 mm = 5'0", but HIGH(1536) = 6
+	cp HIGH(1536)
 	jr nz, .CheckMagikarpArea
 
 ; 5% chance of skipping both size checks
@@ -6174,7 +6179,7 @@
 	jr c, .CheckMagikarpArea
 ; Try again if length >= 1616 mm (i.e. if LOW(length) >= 4 inches)
 	ld a, [wMagikarpLength + 1]
-	cp LOW(1616) ; should be "cp 4", since 1616 mm = 5'4", but LOW(1616) = 80
+	cp LOW(1616)
 	jr nc, .GenerateDVs
 
 ; 20% chance of skipping this check
@@ -6183,23 +6188,11 @@
 	jr c, .CheckMagikarpArea
 ; Try again if length >= 1600 mm (i.e. if LOW(length) >= 3 inches)
 	ld a, [wMagikarpLength + 1]
-	cp LOW(1600) ; should be "cp 3", since 1600 mm = 5'3", but LOW(1600) = 64
+	cp LOW(1600)
 	jr nc, .GenerateDVs
 
 .CheckMagikarpArea:
-; The "jr z" checks are supposed to be "jr nz".
-
-; Instead, all maps in GROUP_LAKE_OF_RAGE (Mahogany area)
-; and Routes 20 and 44 are treated as Lake of Rage.
-
-; This also means Lake of Rage Magikarp can be smaller than ones
-; caught elsewhere rather than the other way around.
-
-; Intended behavior enforces a minimum size at Lake of Rage.
-; The real behavior prevents a minimum size in the Lake of Rage area.
-
-; Moreover, due to the check not being translated to feet+inches, all Magikarp
-; smaller than 4'0" may be caught by the filter, a lot more than intended.
+; BUG: Magikarp in Lake of Rage are shorter, not longer (see docs/bugs_and_glitches.md)
 	ld a, [wMapGroup]
 	cp GROUP_LAKE_OF_RAGE
 	jr z, .Happiness
@@ -6212,7 +6205,7 @@
 	jr c, .Happiness
 ; Try again if length < 1024 mm (i.e. if HIGH(length) < 3 feet)
 	ld a, [wMagikarpLength]
-	cp HIGH(1024) ; should be "cp 3", since 1024 mm = 3'4", but HIGH(1024) = 4
+	cp HIGH(1024)
 	jr c, .GenerateDVs ; try again
 
 ; Finally done with DVs
@@ -6805,6 +6798,7 @@
 	ld hl, wBattleMonAttack
 	ld c, 4
 .CheckBadge:
+; BUG: Glacier Badge may not boost Special Defense depending on the value of Special Attack (see docs/bugs_and_glitches.md)
 	ld a, b
 	srl b
 	call c, BoostStat
@@ -6814,9 +6808,6 @@
 	srl b
 	dec c
 	jr nz, .CheckBadge
-; Check GlacierBadge again for Special Defense.
-; This check is buggy because it assumes that a is set by the "ld a, b" in the above loop,
-; but it can actually be overwritten by the call to BoostStat.
 	srl a
 	call c, BoostStat
 	ret
@@ -7637,6 +7628,7 @@
 	ld hl, GoMonText
 	jr z, .skip_to_textbox
 
+; BUG: Switching out or switching against a Pokémon with max HP below 4 freezes the game (see docs/bugs_and_glitches.md)
 	; compute enemy health remaining as a percentage
 	xor a
 	ldh [hMultiplicand + 0], a
--- a/engine/battle/effect_commands.asm
+++ b/engine/battle/effect_commands.asm
@@ -1401,13 +1401,9 @@
 	and a
 	jr z, CheckTypeMatchup
 	ld hl, wBattleMonType1
+ 	; fallthrough
 CheckTypeMatchup:
-; There is an incorrect assumption about this function made in the AI related code: when
-; the AI calls CheckTypeMatchup (not BattleCheckTypeMatchup), it assumes that placing the
-; offensive type in a will make this function do the right thing. Since a is overwritten,
-; this assumption is incorrect. A simple fix would be to load the move type for the
-; current move into a in BattleCheckTypeMatchup, before falling through, which is
-; consistent with how the rest of the code assumes this code works like.
+; BUG: AI makes a false assumption about CheckTypeMatchup (see docs/bugs_and_glitches.md)
 	push hl
 	push de
 	push bc
@@ -1865,9 +1861,7 @@
 	jr z, .got_move_chance
 	ld hl, wEnemyMoveStruct + MOVE_CHANCE
 .got_move_chance
-
-	; BUG: 1/256 chance to fail even for a 100% effect chance,
-	; since carry is not set if BattleRandom == [hl] == 255
+; BUG: Moves with a 100% secondary effect chance will not trigger it in 1/256 uses (see docs/bugs_and_glitches.md)
 	call BattleRandom
 	cp [hl]
 	pop hl
@@ -2089,6 +2083,7 @@
 	inc hl
 	ld a, [hl]
 
+; BUG: Beat Up may fail to raise Substitute (see docs/bugs_and_glitches.md)
 	cp EFFECT_MULTI_HIT
 	jr z, .multihit
 	cp EFFECT_DOUBLE_HIT
@@ -2510,6 +2505,7 @@
 	pop bc
 	ret nz
 
+; BUG: Metal Powder can increase damage taken with boosted (Special) Defense (see docs/bugs_and_glitches.md)
 	ld a, c
 	srl a
 	add c
@@ -2646,6 +2642,7 @@
 	inc l
 
 .finish
+; BUG: Reflect and Light Screen can make (Special) Defense wrap around above 1024 (see docs/bugs_and_glitches.md)
 	ld a, [wLinkMode]
 	cp LINK_COLOSSEUM
 	jr z, .done
@@ -2772,6 +2769,7 @@
 	ret nz
 
 ; Double the stat
+; BUG: Thick Club and Light Ball can make (Special) Attack wrap around above 1024 (see docs/bugs_and_glitches.md)
 	sla l
 	rl h
 	ret
@@ -2901,9 +2899,8 @@
 
 BattleCommand_DamageCalc:
 ; Return a damage value for move power d, player level e, enemy defense c and player attack b.
+; BUG: Confusion damage is affected by type-boosting items and Explosion/Self-Destruct doubling (see docs/bugs_and_glitches.md)
 
-; Return 1 if successful, else 0.
-
 	ld a, BATTLE_VARS_MOVE_EFFECT
 	call GetBattleVar
 
@@ -5263,6 +5260,7 @@
 	jr .double_hit
 
 .only_one_beatup
+; BUG: Beat Up works incorrectly with only one Pokémon in the party (see docs/bugs_and_glitches.md)
 	ld a, BATTLE_VARS_SUBSTATUS3
 	call GetBattleVarAddr
 	res SUBSTATUS_IN_LOOP, [hl]
@@ -6546,7 +6544,7 @@
 INCLUDE "engine/battle/move_effects/thunder.asm"
 
 CheckHiddenOpponent:
-; BUG: This routine is completely redundant and introduces a bug, since BattleCommand_CheckHit does these checks properly.
+; BUG: Lock-On and Mind Reader don't always bypass Fly and Dig (see docs/bugs_and_glitches.md)
 	ld a, BATTLE_VARS_SUBSTATUS3_OPP
 	call GetBattleVar
 	and 1 << SUBSTATUS_FLYING | 1 << SUBSTATUS_UNDERGROUND
--- a/engine/battle/move_effects/beat_up.asm
+++ b/engine/battle/move_effects/beat_up.asm
@@ -24,6 +24,7 @@
 	ld [wCurBeatUpPartyMon], a
 
 .got_mon
+; BUG: Beat Up can desynchronize link battles (see docs/bugs_and_glitches.md)
 	ld a, [wCurBeatUpPartyMon]
 	ld hl, wPartyMonNicknames
 	call GetNickname
@@ -35,8 +36,6 @@
 	ld a, [wCurBeatUpPartyMon]
 	ld c, a
 	ld a, [wCurBattleMon]
-	; BUG: this can desynchronize link battles
-	; Change "cp [hl]" to "cp c" to fix
 	cp [hl]
 	ld hl, wBattleMonStatus
 	jr z, .active_mon
@@ -196,6 +195,7 @@
 	jp SkipToBattleCommand
 
 BattleCommand_BeatUpFailText:
+; BUG: Beat Up may trigger King's Rock even if it failed (see docs/bugs_and_glitches.md)
 	ld a, [wBeatUpHitAtLeastOnce]
 	and a
 	ret nz
--- a/engine/battle/move_effects/belly_drum.asm
+++ b/engine/battle/move_effects/belly_drum.asm
@@ -1,7 +1,5 @@
 BattleCommand_BellyDrum:
-; This command is buggy because it raises the user's attack
-; before checking that it has enough HP to use the move.
-; Swap the order of these two blocks to fix.
+; BUG: Belly Drum sharply boosts Attack even with under 50% HP (see docs/bugs_and_glitches.md)
 	call BattleCommand_AttackUp2
 	ld a, [wAttackMissed]
 	and a
--- a/engine/battle/move_effects/counter.asm
+++ b/engine/battle/move_effects/counter.asm
@@ -34,7 +34,7 @@
 	cp SPECIAL
 	ret nc
 
-	; BUG: Move should fail with all non-damaging battle actions
+; BUG: Counter and Mirror Coat still work if the opponent uses an item (see docs/bugs_and_glitches.md)
 	ld hl, wCurDamage
 	ld a, [hli]
 	or [hl]
--- a/engine/battle/move_effects/frustration.asm
+++ b/engine/battle/move_effects/frustration.asm
@@ -1,4 +1,5 @@
 BattleCommand_FrustrationPower:
+; BUG: Return and Frustration deal no damage when the user's happiness is low or high, respectively (see docs/bugs_and_glitches.md)
 	push bc
 	ld hl, wBattleMonHappiness
 	ldh a, [hBattleTurn]
--- a/engine/battle/move_effects/mirror_coat.asm
+++ b/engine/battle/move_effects/mirror_coat.asm
@@ -35,7 +35,7 @@
 	cp SPECIAL
 	ret c
 
-	; BUG: Move should fail with all non-damaging battle actions
+; BUG: Counter and Mirror Coat still work if the opponent uses an item (see docs/bugs_and_glitches.md)
 	ld hl, wCurDamage
 	ld a, [hli]
 	or [hl]
--- a/engine/battle/move_effects/present.asm
+++ b/engine/battle/move_effects/present.asm
@@ -1,4 +1,5 @@
 BattleCommand_Present:
+; BUG: Present damage is incorrect in link battles (see docs/bugs_and_glitches.md)
 	ld a, [wLinkMode]
 	cp LINK_COLOSSEUM
 	jr z, .colosseum_skippush
--- a/engine/battle/move_effects/return.asm
+++ b/engine/battle/move_effects/return.asm
@@ -1,4 +1,5 @@
 BattleCommand_HappinessPower:
+; BUG: Return and Frustration deal no damage when the user's happiness is low or high, respectively (see docs/bugs_and_glitches.md)
 	push bc
 	ld hl, wBattleMonHappiness
 	ldh a, [hBattleTurn]
--- a/engine/battle/move_effects/sketch.asm
+++ b/engine/battle/move_effects/sketch.asm
@@ -12,6 +12,7 @@
 	call CheckSubstituteOpp
 	jp nz, .fail
 ; If the opponent is transformed, fail.
+; BUG: A Transformed Pokémon can use Sketch and learn otherwise unobtainable moves (see docs/bugs_and_glitches.md)
 	ld a, BATTLE_VARS_SUBSTATUS5_OPP
 	call GetBattleVarAddr
 	bit SUBSTATUS_TRANSFORMED, [hl]
--- a/engine/battle/move_effects/teleport.asm
+++ b/engine/battle/move_effects/teleport.asm
@@ -66,6 +66,7 @@
 	inc c
 	; Generate a number less than c
 .loop_enemy
+; BUG: Wild Pokémon can always Teleport regardless of level difference (see docs/bugs_and_glitches.md)
 	call BattleRandom
 	cp c
 	jr nc, .loop_enemy
@@ -72,8 +73,6 @@
 	; b = player level / 4
 	srl b
 	srl b
-	; This should be "jr c, .failed"
-	; As written, it makes enemy use of Teleport always succeed if able
 	cp b
 	jr nc, .run_away
 
--- a/engine/battle/start_battle.asm
+++ b/engine/battle/start_battle.asm
@@ -93,7 +93,7 @@
 	cp RED
 	jr z, .done
 
-	; They should have included EXECUTIVEM, EXECUTIVEF, and SCIENTIST too...
+; BUG: Team Rocket battle music is not used for Executives or Scientists (see docs/bugs_and_glitches.md)
 	ld de, MUSIC_ROCKET_BATTLE
 	cp GRUNTM
 	jr z, .done
--- a/engine/battle_anims/anim_commands.asm
+++ b/engine/battle_anims/anim_commands.asm
@@ -653,9 +653,9 @@
 	ret
 
 BattleAnimCmd_ClearObjs:
-; BUG: This function only clears the first 6⅔ objects
+; BUG: BattleAnimCmd only clears the first 6⅔ objects (see docs/bugs_and_glitches.md)
 	ld hl, wActiveAnimObjects
-	ld a, $a0 ; should be NUM_ANIM_OBJECTS * BATTLEANIMSTRUCT_LENGTH
+	ld a, $a0
 .loop
 	ld [hl], 0
 	inc hl
--- a/engine/events/haircut.asm
+++ b/engine/events/haircut.asm
@@ -37,13 +37,6 @@
 	call CopyPokemonName_Buffer1_Buffer3
 	pop hl
 	call Random
-; Bug: Subtracting $ff from $ff fails to set c.
-; This can result in overflow into the next data array.
-; In the case of getting a grooming from Daisy, we bleed
-; into CopyPokemonName_Buffer1_Buffer3, which passes
-; $d0 to ChangeHappiness and returns $73 to the script.
-; The end result is that there is a 0.4% chance your
-; Pokemon's happiness will not change at all.
 .loop
 	sub [hl]
 	jr c, .ok
--- a/engine/events/halloffame.asm
+++ b/engine/events/halloffame.asm
@@ -363,8 +363,9 @@
 	call ClearBGPalettes
 	pop hl
 	call DisplayHOFMon
+; BUG: A "HOF Master!" title for 200-Time Famers is defined but inaccessible (see docs/bugs_and_glitches.md)
 	ld a, [wHallOfFameTempWinCount]
-	cp HOF_MASTER_COUNT + 1 ; should be HOF_MASTER_COUNT
+	cp HOF_MASTER_COUNT + 1
 	jr c, .print_num_hof
 	ld de, .HOFMaster
 	hlcoord 1, 2
--- a/engine/events/magikarp.asm
+++ b/engine/events/magikarp.asm
@@ -278,12 +278,11 @@
 	ret
 
 .BCLessThanDE:
-; Intention: Return bc < de.
-; Reality: Return b < d.
+; BUG: Magikarp lengths can be miscalculated (see docs/bugs_and_glitches.md)
 	ld a, b
 	cp d
 	ret c
-	ret nc ; whoops
+	ret nc
 	ld a, c
 	cp e
 	ret
--- a/engine/events/overworld.asm
+++ b/engine/events/overworld.asm
@@ -400,6 +400,7 @@
 	special UpdateTimePals
 
 UsedSurfScript:
+; BUG: Surfing directly across a map connection does not load the new map (see docs/bugs_and_glitches.md)
 	writetext UsedSurfText ; "used SURF!"
 	waitbutton
 	closetext
--- a/engine/games/slot_machine.asm
+++ b/engine/games/slot_machine.asm
@@ -483,12 +483,13 @@
 	jr c, .okay
 	inc de
 .okay
+; BUG: Slot machine payout sound effects cut each other off (see docs/bugs_and_glitches.md)
 	ld [hl], e
 	dec hl
 	ld [hl], d
 	ld a, [wSlotsDelay]
 	and $7
-	ret z ; ret nz would be more appropriate
+	ret z
 	ld de, SFX_GET_COIN_FROM_SLOTS
 	call PlaySFX
 	ret
--- a/engine/items/item_effects.asm
+++ b/engine/items/item_effects.asm
@@ -210,6 +210,7 @@
 ; NoEffect would be appropriate, with the table then being NUM_ITEMS long.
 
 PokeBallEffect:
+; BUG: The Dude's catching tutorial may crash if his Poké Ball can't be used (see docs/bugs_and_glitches.md)
 	ld a, [wBattleMode]
 	dec a
 	jp nz, UseBallInTrainerBattle
@@ -226,6 +227,7 @@
 	jp z, Ball_BoxIsFullMessage
 
 .room_in_party
+; BUG: Using a Park Ball in non-Contest battles has a corrupt animation (see docs/bugs_and_glitches.md)
 	xor a
 	ld [wWildMon], a
 	ld a, [wCurItem]
@@ -334,17 +336,12 @@
 	jr nz, .statuscheck
 	ld a, 1
 .statuscheck
-; This routine is buggy. It was intended that SLP and FRZ provide a higher
-; catch rate than BRN/PSN/PAR, which in turn provide a higher catch rate than
-; no status effect at all. But instead, it makes BRN/PSN/PAR provide no
-; benefit.
-; Uncomment the line below to fix this.
+; BUG: BRN/PSN/PAR do not affect catch rate (see docs/bugs_and_glitches.md)
 	ld b, a
 	ld a, [wEnemyMonStatus]
 	and 1 << FRZ | SLP_MASK
 	ld c, 10
 	jr nz, .addstatus
-	; ld a, [wEnemyMonStatus]
 	and a
 	ld c, 5
 	jr nz, .addstatus
@@ -356,13 +353,10 @@
 	ld a, $ff
 .max_1
 
-	; BUG: farcall overwrites a, and GetItemHeldEffect takes b anyway.
-	; This is probably the reason the HELD_CATCH_CHANCE effect is never used.
-	; Uncomment the line below to fix.
+; BUG: HELD_CATCH_CHANCE has no effect (see docs/bugs_and_glitches.md)
 	ld d, a
 	push de
 	ld a, [wBattleMonItem]
-	; ld b, a
 	farcall GetItemHeldEffect
 	ld a, b
 	cp HELD_CATCH_CHANCE
@@ -446,9 +440,7 @@
 	push af
 	set SUBSTATUS_TRANSFORMED, [hl]
 
-; This code is buggy. Any wild Pokémon that has Transformed will be
-; caught as a Ditto, even if it was something else like Mew.
-; To fix, do not set [wTempEnemyMonSpecies] to DITTO.
+; BUG: Catching a Transformed Pokémon always catches a Ditto (see docs/bugs_and_glitches.md)
 	bit SUBSTATUS_TRANSFORMED, a
 	jr nz, .ditto
 	jr .not_ditto
@@ -761,13 +753,10 @@
 	ret
 
 HeavyBall_GetDexEntryBank:
-; This function is buggy.
-; It gets the wrong bank for Kadabra (64), Tauros (128), and Sunflora (192).
-; Uncomment the line below to fix this.
+; BUG: Heavy Ball uses wrong weight value for three Pokémon (see docs/bugs_and_glitches.md)
 	push hl
 	push de
 	ld a, [wEnemyMonSpecies]
-	; dec a
 	rlca
 	rlca
 	maskbits NUM_DEX_ENTRY_BANKS
@@ -905,9 +894,6 @@
 	ret
 
 MoonBallMultiplier:
-; This function is buggy.
-; Intent:  multiply catch rate by 4 if mon evolves with moon stone
-; Reality: no boost
 	push bc
 	ld a, [wTempEnemyMonSpecies]
 	dec a
@@ -931,9 +917,7 @@
 	inc hl
 	inc hl
 
-; Moon Stone's constant from Pokémon Red is used.
-; No Pokémon evolve with Burn Heal,
-; so Moon Balls always have a catch rate of 1×.
+; BUG: Moon Ball does not boost catch rate (see docs/bugs_and_glitches.md)
 	push bc
 	ld a, BANK("Evolutions and Attacks")
 	call GetFarByte
@@ -951,9 +935,6 @@
 	ret
 
 LoveBallMultiplier:
-; This function is buggy.
-; Intent:  multiply catch rate by 8 if mons are of same species, different sex
-; Reality: multiply catch rate by 8 if mons are of same species, same sex
 
 	; does species match?
 	ld a, [wTempEnemyMonSpecies]
@@ -974,9 +955,9 @@
 	jr c, .done1 ; no effect on genderless
 
 	ld d, 0 ; male
-	jr nz, .playermale
+	jr nz, .got_player_gender
 	inc d   ; female
-.playermale
+.got_player_gender
 
 	; check wild mon species
 	push de
@@ -988,15 +969,16 @@
 	jr c, .done2 ; no effect on genderless
 
 	ld d, 0 ; male
-	jr nz, .wildmale
+	jr nz, .got_wild_gender
 	inc d   ; female
-.wildmale
+.got_wild_gender
 
+; BUG: Love Ball boosts catch rate for the wrong gender (see docs/bugs_and_glitches.md)
 	ld a, d
 	pop de
 	cp d
 	pop bc
-	ret nz ; for the intended effect, this should be "ret z"
+	ret nz
 
 	sla b
 	jr c, .max
@@ -1016,11 +998,6 @@
 	ret
 
 FastBallMultiplier:
-; This function is buggy.
-; Intent:  multiply catch rate by 4 if enemy mon is in one of the three
-;          FleeMons tables.
-; Reality: multiply catch rate by 4 if enemy mon is one of the first three in
-;          the first FleeMons table.
 	ld a, [wTempEnemyMonSpecies]
 	ld c, a
 	ld hl, FleeMons
@@ -1027,6 +1004,7 @@
 	ld d, 3
 
 .loop
+; BUG: Fast Ball only boosts catch rate for three Pokémon (see docs/bugs_and_glitches.md)
 	ld a, BANK(FleeMons)
 	call GetFarByte
 
@@ -1034,7 +1012,7 @@
 	cp -1
 	jr z, .next
 	cp c
-	jr nz, .next ; for the intended effect, this should be "jr nz, .loop"
+	jr nz, .next
 	sla b
 	jr c, .max
 
--- a/engine/movie/credits.asm
+++ b/engine/movie/credits.asm
@@ -76,6 +76,7 @@
 
 	call GetCreditsPalette
 	call SetPalettes
+; BUG: Credits sequence changes move selection menu behavior (see docs/bugs_and_glitches.md)
 	ldh a, [hVBlank]
 	push af
 	ld a, $5
--- a/engine/overworld/events.asm
+++ b/engine/overworld/events.asm
@@ -554,7 +554,7 @@
 	ld a, [hl]
 	and %00001111
 
-; Bug: If IsInArray returns nc, data at bc will be executed as code.
+; BUG: TryObjectEvent arbitrary code execution (see docs/bugs_and_glitches.md)
 	push bc
 	ld de, 3
 	ld hl, ObjectEventTypeArray
@@ -569,7 +569,6 @@
 	jp hl
 
 .nope
-	; pop bc
 	xor a
 	ret
 
--- a/engine/overworld/map_objects.asm
+++ b/engine/overworld/map_objects.asm
@@ -2689,7 +2689,7 @@
 	add hl, bc
 	ld a, [hl]
 	cp -1
-	jp z, .set_standing ; a jr would have been appropriate here
+	jp z, .set_standing
 	push bc
 	call GetMapObject
 	ld hl, MAPOBJECT_MOVEMENT
--- a/engine/overworld/npc_movement.asm
+++ b/engine/overworld/npc_movement.asm
@@ -4,10 +4,10 @@
 	bit SWIMMING_F, [hl]
 	jr z, .not_swimming
 
+; BUG: Swimming NPCs aren't limited by their movement radius (see docs/bugs_and_glitches.md)
 	ld hl, OBJECT_FLAGS1
 	add hl, bc
-	bit NOCLIP_TILES_F, [hl] ; lost, uncomment next line to fix
-	; jr nz, .noclip_tiles
+	bit NOCLIP_TILES_F, [hl]
 	push hl
 	push bc
 	call WillObjectBumpIntoLand
--- a/engine/overworld/overworld.asm
+++ b/engine/overworld/overworld.asm
@@ -346,8 +346,7 @@
 	ret
 
 LoadSpriteGFX:
-; Bug: b is not preserved, so it's useless as a next count.
-; Uncomment the lines below to fix.
+; BUG: LoadSpriteGFX does not limit the capacity of UsedSprites (see docs/bugs_and_glitches.md)
 
 	ld hl, wUsedSprites
 	ld b, SPRITE_GFX_LIST_CAPACITY
@@ -366,9 +365,7 @@
 	ret
 
 .LoadSprite:
-	; push bc
 	call GetSprite
-	; pop bc
 	ld a, l
 	ret
 
--- a/engine/overworld/player_movement.asm
+++ b/engine/overworld/player_movement.asm
@@ -391,14 +391,9 @@
 	db FACE_UP | FACE_LEFT    ; COLL_HOP_UP_LEFT
 
 .CheckWarp:
-; Bug: Since no case is made for STANDING here, it will check
-; [.EdgeWarps + $ff]. This resolves to $3e.
-; This causes wWalkingIntoEdgeWarp to be nonzero when standing on tile $3e,
-; making bumps silent.
+; BUG: No bump noise if standing on tile $3E (see docs/bugs_and_glitches.md)
 
 	ld a, [wWalkingDirection]
-	; cp STANDING
-	; jr z, .not_warp
 	ld e, a
 	ld d, 0
 	ld hl, .EdgeWarps
@@ -410,7 +405,6 @@
 	ld a, TRUE
 	ld [wWalkingIntoEdgeWarp], a
 	ld a, [wWalkingDirection]
-	; This is in the wrong place.
 	cp STANDING
 	jr z, .not_warp
 
--- a/engine/overworld/scripting.asm
+++ b/engine/overworld/scripting.asm
@@ -1240,11 +1240,7 @@
 	; fallthrough
 
 ScriptCall:
-; Bug: The script stack has a capacity of 5 scripts, yet there is
-; nothing to stop you from pushing a sixth script.  The high part
-; of the script address can then be overwritten by modifications
-; to wScriptDelay, causing the script to return to the rst/interrupt
-; space.
+; BUG: ScriptCall can overflow wScriptStack and crash (see docs/bugs_and_glitches.md)
 
 	push de
 	ld hl, wScriptStackSize
--- a/engine/overworld/wildmons.asm
+++ b/engine/overworld/wildmons.asm
@@ -313,14 +313,14 @@
 	inc b
 ; Store the level
 .ok
+; BUG: ChooseWildEncounter doesn't really validate the wild Pokemon species (see docs/bugs_and_glitches.md)
 	ld a, b
 	ld [wCurPartyLevel], a
 	ld b, [hl]
-	; ld a, b
 	call ValidateTempWildMonSpecies
 	jr c, .nowildbattle
 
-	ld a, b ; This is in the wrong place.
+	ld a, b
 	cp UNOWN
 	jr nz, .done
 
--- a/engine/phone/phone.asm
+++ b/engine/phone/phone.asm
@@ -498,6 +498,7 @@
 	ld [hl], "☎"
 	inc hl
 	inc hl
+; BUG: The unused phonecall script command may crash (see docs/bugs_and_glitches.md)
 	ld a, [wPhoneScriptBank]
 	ld b, a
 	ld a, [wPhoneCaller]
--- a/engine/pokedex/pokedex.asm
+++ b/engine/pokedex/pokedex.asm
@@ -465,6 +465,7 @@
 	ret
 
 .Cry:
+; BUG: Playing Entei's Pokédex cry can distort Raikou's and Suicune's (see docs/bugs_and_glitches.md)
 	call Pokedex_GetSelectedMon
 	ld a, [wTempSpecies]
 	call GetCryIndex
--- a/engine/pokemon/breeding.asm
+++ b/engine/pokemon/breeding.asm
@@ -620,6 +620,7 @@
 	ret
 
 GetEggFrontpic:
+; BUG: A hatching Unown egg would not show the right letter (see docs/bugs_and_glitches.md)
 	push de
 	ld [wCurPartySpecies], a
 	ld [wCurSpecies], a
--- a/engine/pokemon/experience.asm
+++ b/engine/pokemon/experience.asm
@@ -32,6 +32,7 @@
 
 CalcExpAtLevel:
 ; (a/b)*n**3 + c*n**2 + d*n - e
+; BUG: Experience underflow for level 1 Pokémon with Medium-Slow growth rate (see docs/bugs_and_glitches.md)
 	ld a, [wBaseGrowthRate]
 	add a
 	add a
--- a/engine/pokemon/move_mon.asm
+++ b/engine/pokemon/move_mon.asm
@@ -879,6 +879,7 @@
 	ld a, TRUE
 	ld [wSkipMovesBeforeLevelUp], a
 	predef FillMoves
+; BUG: Pokémon deposited in the Day-Care might lose experience (see docs/bugs_and_glitches.md)
 	ld a, [wPartyCount]
 	dec a
 	ld [wCurPartyMon], a
--- a/engine/pokemon/party_menu.asm
+++ b/engine/pokemon/party_menu.asm
@@ -385,6 +385,7 @@
 	ret
 
 .DetermineCompatibility:
+; BUG: Only the first three evolution entries can have Stone compatibility reported correctly (see docs/bugs_and_glitches.md)
 	ld de, wStringBuffer1
 	ld a, BANK(EvosAttacksPointers)
 	ld bc, 2
@@ -399,6 +400,7 @@
 	call FarCopyBytes
 	ld hl, wStringBuffer1
 .loop2
+; BUG: EVOLVE_STAT can break Stone compatibility reporting (see docs/bugs_and_glitches.md)
 	ld a, [hli]
 	and a
 	jr z, .nope
--- a/engine/pokemon/search_owned.asm
+++ b/engine/pokemon/search_owned.asm
@@ -56,6 +56,7 @@
 	and a
 	ret z
 
+; BUG: CheckOwnMon does not check the Day-Care (see docs/bugs_and_glitches.md)
 	ld d, a
 	ld e, 0
 	ld hl, wPartyMon1Species
@@ -221,7 +222,8 @@
 
 	ld hl, wPlayerName
 
-rept NAME_LENGTH_JAPANESE - 2 ; should be PLAYER_NAME_LENGTH - 2
+; BUG: CheckOwnMon only checks the first five letters of OT names (see docs/bugs_and_glitches.md)
+rept NAME_LENGTH_JAPANESE - 2
 	ld a, [de]
 	cp [hl]
 	jr nz, .notfound
--- a/home/init.asm
+++ b/home/init.asm
@@ -186,6 +186,7 @@
 ClearWRAM::
 ; Wipe swappable WRAM banks (1-7)
 ; Assumes CGB or AGB
+; BUG: ClearWRAM only clears WRAM bank 1 (see docs/bugs_and_glitches.md)
 
 	ld a, 1
 .bank_loop
@@ -198,7 +199,7 @@
 	pop af
 	inc a
 	cp 8
-	jr nc, .bank_loop ; Should be jr c
+	jr nc, .bank_loop
 	ret
 
 ClearsScratch::
--- a/home/map.asm
+++ b/home/map.asm
@@ -146,12 +146,10 @@
 	ld e, l
 	ld d, h
 	; Set hl to the address of the current metatile data ([wTilesetBlocksAddress] + (a) tiles).
-	; This is buggy; it wraps around past 128 blocks.
-	; To fix, uncomment the line below.
-	add a ; Comment or delete this line to fix the above bug.
+; BUG: LoadMetatiles wraps around past 128 blocks (see docs/bugs_and_glitches.md)
+	add a
 	ld l, a
 	ld h, 0
-	; add hl, hl
 	add hl, hl
 	add hl, hl
 	add hl, hl
@@ -584,18 +582,16 @@
 	call CopyMapObjectEvents
 
 ; get NUM_OBJECTS - [wCurMapObjectEventCount]
+; BUG: ReadObjectEvents overflows into wObjectMasks (see docs/bugs_and_glitches.md)
 	ld a, [wCurMapObjectEventCount]
 	ld c, a
-	ld a, NUM_OBJECTS ; - 1
+	ld a, NUM_OBJECTS
 	sub c
 	jr z, .skip
-	; jr c, .skip
 
 	; could have done "inc hl" instead
 	ld bc, 1
 	add hl, bc
-; Fill the remaining sprite IDs and y coords with 0 and -1, respectively.
-; Bleeds into wObjectMasks due to a bug.  Uncomment the above code to fix.
 	ld bc, MAPOBJECT_LENGTH
 .loop
 	ld [hl],  0
--- a/maps/DragonsDenB1F.asm
+++ b/maps/DragonsDenB1F.asm
@@ -41,6 +41,7 @@
 	endcallback
 
 DragonsDenB1F_ClairScene:
+; BUG: Clair can give TM24 Dragonbreath twice (see docs/bugs_and_glitches.md)
 	appear DRAGONSDENB1F_CLAIR
 	opentext
 	writetext ClairText_Wait