bug-author

name	bug-author
description	Create reverse Rust puzzles with intentional, educational bugs.

Bug Author Skill

Create reverse Rust puzzles.

A reverse puzzle starts from flawed code and asks the learner to debug it.

The learner already knows Python, TypeScript, C++, Java, and Go. The bug should teach Rust-specific reasoning, not generic debugging trivia.

Core principle

The bug must be intentional, realistic, and educational.

Do not create random syntax errors.

Prefer one primary bug pattern per lab.

Good bug patterns

• moved value used after move
• immutable binding mutated by accident, when related to ownership flow
• returning reference to local value
• lifetime annotation used as a magic fix
• unnecessary clone hiding ownership misunderstanding
• unwrap at a recoverable error boundary
• swallowed error / wrong error variant
• iter vs into_iter ownership mistake
• half-open interval implemented as closed interval
• String returned where &str would be sufficient, or the reverse
• trait bound too narrow or too broad
• object safety misunderstanding
• public API forcing unnecessary ownership
• borrowed data crossing an async boundary

Required files

Each bug lab must include:

• Cargo.toml
• README.md
• Bug.toml
• src/lib.rs
• tests/judge.rs

Recommended:

• notes/diagnosis.md
• notes/solution.patch

Bug.toml metadata

id = "b20_example_bug"
title = "Example Bug"
level = "B20"
track = "lifetime"
kind = "compile_fail"
difficulty = "medium"
status = "active"
bug_patterns = ["returning-reference-to-local"]
estimated_minutes = 35
expected_initial_state = "cargo check fails"
success_condition = "cargo test passes"

README sections

1. Situation
2. Current state
3. Your task
4. Commands
5. What to investigate
6. Rust concepts
7. Constraints
8. Optional stretch

Do not reveal the full fix in README.

Diagnosis notes

notes/diagnosis.md should explain:

• initial symptom
• root cause
• wrong but tempting fix
• correct repair strategy
• Rust concept learned

Solution patch

notes/solution.patch may include a reference patch.

Keep it minimal.

Test design

For compile_fail labs:

• The initial failure must be intentional.
• Tests should pass after a reasonable repair.
• The README should say the code does not compile.

For test_fail labs:

• The initial code should compile.
• The tests should reveal the bug.
• Avoid too many unrelated failures.

For design_smell labs:

• Include review goals and tests if possible.
• The improvement should be concrete, not subjective.