Untitled Lesson
Skill Matrix
UNLOCK NODES BY LEARNING NEW TAGS.
Why is an AI assistant generally unable to reliably document the "why" behind a specific design decision without additional context being provided?
💻 Code Challenge | +75 XP
Write a documentation prompt for a retry-logic function that supplies the actual business reasoning (a specific historical justification) as explicit context, rather than asking the AI to document the reasoning without that context.
A new team member relied on an AI-generated code comment explaining why a specific retry count was chosen, but the explanation turned out to be a plausible-sounding fabrication with no basis in actual history. Reorder the steps to fix the documentation process.
Task: Reorder the blocks in logical sequence to solve the problem.
A.D.A. Interface
Adaptive Didactic Assistant
Pascual Vila
Frontend Instructor // Code Syllabus
The Error //
Asking an AI assistant to document the reasoning ("why") behind a design decision without supplying the actual context
// Risky: fabricated-sounding reasoning with no actual basis
"Document why we retry 3 times" (no context given)
// Correct: real context supplied, AI structures it clearly
"We retry 3 times because [actual historical reason]. Document this clearly."The Solution //
The real reasoning behind a decision — a specific business constraint, a past incident, a workaround for a dependency's bug — exists only in institutional knowledge the model has no access to. Without that context supplied explicitly, a generated explanation of "why" is a plausible-sounding guess, not a documented fact, and can actively mislead a future reader who trusts it.
The Error //
Trusting generated documentation for style and clarity without reviewing it for factual accuracy against the actual code
// Insufficient review: checked for clarity, not accuracy
// Correct: verified against the ACTUAL code behavior specifically
// Does the documented parameter behavior match what the code really does?The Solution //
A well-written, professional-sounding piece of documentation that is subtly factually incorrect about a parameter's actual behavior or an edge case is arguably more dangerous than no documentation at all, since a future reader is likely to trust and act on it without independently verifying it against the code.