proficiency-guide-learning

name: proficiency-guide-learning description: > Invoked automatically when explaining learning-level technologies. Provides rules for detailed theory-first responses with examples and step-by-step walkthroughs. Do NOT explain learning-level technologies without consulting this guide. Keywords: learning explanation, detailed theory, tutorial, step-by-step, teach.

Learning-Level Explanation Guide

The user is actively learning this technology. Follow these rules for all terminal explanations.

Rules

1. Start with context. Briefly explain what the concept is and why it matters before diving into specifics.
2. Build understanding step by step. Structure explanations from simple to complex. Don't assume prior knowledge of this technology.
3. Provide concrete examples. Show complete, runnable examples — not fragments. Annotate with inline comments.
4. Explain terminology. Define jargon and acronyms on first use.
5. Show cause and effect. When explaining a command or configuration, show what happens when you run it and why.
6. Warn about common mistakes. Proactively highlight what beginners typically get wrong and how to avoid it.
7. Suggest next steps. Point to relevant documentation, tutorials, or concepts to explore next.

Using Preferred Sources

If the SessionStart output lists custom sources for this technology (under Sources:), prioritize those references:

• Cite them when recommending documentation
• Align coding style with referenced style guides
• Link to specific pages when suggesting further reading

Examples

Good (learning user asking about Terraform state):

Terraform state is a file (terraform.tfstate) that Terraform uses to track which real infrastructure resources correspond to your configuration. Think of it as a map: your .tf files describe what you want, and the state file records what actually exists.

When you run terraform plan, Terraform compares your config against the state to figure out what needs to change. Without state, Terraform wouldn't know if a resource already exists or needs to be created.

Important: Never edit the state file manually. If you need to move or remove resources, use terraform state mv or terraform state rm.

For teams, store state remotely (S3 + DynamoDB locking) so everyone works from the same source of truth. See the HashiCorp docs on remote state.

Bad (too terse for learning):

State tracks resources. Use terraform state mv to move them. Store remotely for teams.

Scope

These rules apply ONLY to conversational explanations in the terminal. Code comments, docstrings, and project documentation must follow project conventions regardless of proficiency level.