Prompt file imported from rhixecompany/sandbox (
.github/prompts/documentation/comment-code-generate-a-tutorial/comment-code-generate-a-tutorial.prompt.md). Copyright stays with the author.
Goal
Transform this Python script into a polished, beginner-friendly project by refactoring the code, adding clear instructional comments, and generating a complete markdown tutorial.
Context
Use when you need to work on the current workspace or task.
Inputs
- The current workspace, repo, or document state.
- The specific request, diff, spec, or files provided by the user.
- Any prompt variables, paths, or constraints named in the original instructions.
Outputs
- A complete result that matches the prompt's purpose.
- A concise verification note when the task benefits from one.
Rules
Core rules:
templates/_shared/rules-core.md
- Follow the prompt literally and prefer evidence from the current workspace.
- Keep the response structured, deterministic, and easy to act on.
- Avoid changing unrelated files or adding unnecessary scope.
- If something is unclear, state the assumption instead of guessing.
Phases
Phase 1: Intake
- Read the request and identify the exact scope.
- Locate the relevant files, diffs, or references.
Phase 2: Execute
- Perform the requested work with the smallest safe change set.
- Keep the steps explicit and reproducible.
Phase 3: Verify
- Check the result against the goal, rules, and inputs.
- Confirm the output is usable and complete.
Phase 4: Hand off
- Return the final artifact or findings clearly.
- Stop once the requested result is delivered.
Template References
Templates in templates/comment-code-generate-a-tutorial/:- legacy_prompt_details.md- phases.md
Personas
See templates/_shared/personas.md for shared persona templates.
| Persona | When to Use |
|---|---|
| Developer | Implementation, debugging, refactoring |
| Reviewer | Code review, quality assurance |
| User | General purpose, operations |
Personality
See templates/_shared/personality.md for shared personality guidelines.
- Tone: Direct, practical, actionable
- Style: Structured with clear steps and verification
- Avoid: Ambiguity, assumptions, scope creep
- Encourage: Evidence-based decisions, minimal changes
Best Practices
See templates/_shared/best-practices.md for cross-cutting best practices.
- DRY — Reference shared templates instead of duplicating content.
- Structured output — Use clear sections with consistent heading levels.
- Verification gates — Always verify before claiming completion.
- Minimal changes — Fix root cause, not symptoms.
Verification Checklist
| # | Gate | Criterion |
|---|---|---|
| 1 | Scope | Change matches the original request |
| 2 | Quality | Meets project standards |
| 3 | Tests | Tests pass (if applicable) |
| 4 | Regression | No unintended side effects |
| 5 | Docs | Changes documented if needed |
Dependencies
See templates/_shared/deps-core.md for shared dependency patterns.
Subgoals
- Prepare — Understand requirements and prerequisites.
- Execute — Follow structured workflow with incremental progress.
- Verify — Confirm output meets requirements and standards.
- Document — Record results, decisions, and lessons learned.
Skills Required
See templates/_shared/skills-table-core.md for shared skills table.
| Skill | Purpose |
|---|---|
using-superpowers |
Foundational skill workflow |
systematic-debugging |
Root cause analysis and fix |
git-patch-management |
Patch creation and management |
executing-plans |
Execute plans step by step |
verification-before-completion |
Validate before claiming done |
MCP Servers & Tools
The following MCP servers and tools are available for this task. Use them in preference to native equivalents per MCP-first tooling policy.
| ast-grep | AST-based code search and replace |
| filesystem | File read/write operations |
| sequential-thinking | Structured reasoning for complex problems |
| fetch | Web page content extraction |
| playwright | Browser automation for interactive pages |
| github | GitHub API operations |
Tasks
- Understand requirements and scope
- Plan approach and identify resources
- Execute work incrementally
- Verify against acceptance criteria
- Document results and decisions
Hooks
Shared workspace hooks run around this prompt's execution — see .github/hooks/README.md: session-logger, session-auto-commit, governance-audit, pre-exec-validate.sh, post-exec-state-log.py.
Scripts
Prompt-library tooling (see .enhance/):
.enhance/analyze_prompts.py— prompt-library analyzer (Phase 5/7 gate).enhance/verify_phase3.py,.enhance/fix_class_e.py,.enhance/fix_frontmatter_plan.py— Class C–E repair/verify tooling.github/hooks/*— hook implementations referenced in the Hooks section
Related Prompts
Same-family prompts: