Chapter C61 · Interactive Course
Brief a coding task
Observed problems, acceptance criteria, scope, exploration, reproducers and right-sized plans.
Core Learning Concept
Write a task brief from the observed problem, not an assumed implementation. Include the trigger, expected behavior, actual behavior, relevant evidence, and scope. Define what would prove the repair works. Another person should be able to reproduce the problem and review the result from this brief.
What You’ll Learn in This Chapter
-
Read six lines of code without writing any
Follow a small handler's inputs, condition and saved result, and read a test and an error trace against it.
A function performs a named task on input values. Conditional branches direct code flow, returns yield outputs, and storage operations modify persistent external state. Software tests verify behavior by checking exact inputs against anticipated assertions.
-
Start with the observed problem
Describe a trigger and incorrect result.
An observed problem describes what happened under specific conditions. “Submitting an empty name closes the form” is stronger evidence than “the validation function is broken.” State the trigger, expected result, and actual result. Keep the proposed cause separate until the code and runtime evidence support it.
-
Acceptance criteria make done visible
Write one checkable outcome.
Acceptance criteria make completion observable. For the empty-name bug, require that submission stays blocked and a useful message appears, while valid names still save. These criteria guide both implementation and review. Avoid defining success only as changing a particular function when the user-visible behavior is the real goal.
-
Scope limits the change
Name the allowed area and relevant constraints.
Scope identifies the intended change and relevant boundaries. A form-validation repair may not require redesigning the whole account flow. State the behavior to improve and any compatibility constraints, while allowing necessary supporting changes. Clear scope helps distinguish useful work from unrelated edits that increase review burden.
-
Explore before editing
Ask for evidence about the current implementation.
Explore actual codebase execution paths before attempting any edits. Locate entry points, parameter validation, persistence calls, and existing tests directly. Grounding changes in real source code prevents inventing imaginary architectural layers.
-
Supply a minimal reproducer
Use the smallest supplied example that shows the problem.
A minimal reproducer is the smallest reliable set of inputs and steps that shows the problem. Include the environment and any relevant error output. Removing unrelated details makes diagnosis easier, but do not remove a condition that causes the failure. Use synthetic data where it can reproduce the issue.
-
A plan should match the task size
Choose an appropriate next step rather than a ceremonial plan.
A plan should expose the important decisions and verification steps at the task’s scale. A small copy fix may need no formal plan; a cross-component behavior change may need a short sequence. Plans support execution and review, so update them when evidence changes the route to the goal.
-
Write the task card
Assemble a bug brief with a reproducer, one acceptance criterion, an allowed scope and the evidence you want back.