explain

Name: explain
Author: thoughtbot

15stars1forks

How to install explain?

thoughtbot/rails-consultant/explain

$npx -y skills add thoughtbot/rails-consultant --skill explain

Installs into the current project.

Summary

Explain what a piece of code does — a specific file, class, or method in close detail, or a user-facing flow as a concise system overview. What it does and why, not whether it's good.

Files · 1

View on GitHub

SKILL.md

1	## Behavior
2
3	Explain `$ARGUMENTS`. Do the research and deliver the explanation in one pass.
4
5	Determine the mode from the argument:
6
7	- If the argument is a file path, class name, or method — this is a code explanation. Follow the Code Explanation section.
8	- If the argument is a user action, feature, or flow description (e.g. "password reset", "checkout", "authentication") — this is a flow explanation. Follow the Flow Explanation section.
9
10	---
11
12	## Code Explanation
13
14	Start by checking the git history for the file: `git log --oneline -15 <file>` and `git log -1 -p <file>` for the most recent change. Commit messages often reveal the "why" that the code itself doesn't — a bug that was fixed, a refactor that simplified something, a workaround for an external constraint. Note anything that reframes the code before diving into it.
15
16	Then read the code carefully and explain in this order:
17
18	### 1. What it does — in one paragraph
19
20	Plain English. No jargon, no code. Describe what this code accomplishes from the outside — what goes in, what comes out, what changes as a result. Write it the way you'd explain it to the client who asked for the feature.
21
22	### 2. How it does it — walking through the logic
23
24	Narrate the code path in plain English, step by step. For each meaningful chunk:
25
26	- What is this step doing?
27	- Why is it doing it here, in this order?
28	- What would break if it wasn't here?
29
30	Don't narrate every line — skip the obvious. Focus on the parts that require interpretation.
31
32	### 3. Patterns and conventions in use
33
34	Name the Rails, Ruby, or design patterns this code is using — and why they appear here. Examples:
35
36	- "This is a service object following the thoughtbot pattern — one public `call` method, one responsibility"
37	- "This is using `delegate` to avoid Law of Demeter violations"
38	- "This callback is doing what's normally done in a service object — worth noting"
39	- "This is a query object extracting complex AR logic out of the model"
40
41	If the code is using a pattern poorly or unexpectedly, name that too — neutrally. This isn't a review, but understanding requires knowing when something is off-label.
42
43	### 4. What to watch out for
44
45	Any non-obvious behaviour, implicit dependencies, or things that would surprise someone maintaining this code. Not a critique — just "here's what you'd need to know to work safely in this area."
46
47	---
48
49	## Flow Explanation
50
51	Start with the Rails router. Locate the route(s) that correspond to the described flow. From each entry point, trace the execution path through the codebase — controllers, service objects, models, callbacks, jobs, mailers. Follow both success and failure paths.
52
53	Then deliver the explanation in two parts: a diagram and a summary.
54
55	### 1. Diagram
56
57	Render a concise visual flowchart of the system using box-drawing characters. The diagram should show:
58
59	- States and transitions — the lifecycle, not the method calls
60	- Decision points — where the flow branches
61	- Key actions — what happens at each step, described in plain English
62	- Terminal states — where the flow ends
63
64	Conventions:
65
66	- Box-drawing characters for structure: `┌─┐`, `│`, `├──`, `└──`, `▼`, `◄`
67	- Decision points as plain text with branches: `YES` / `NO`
68	- Actions as concise descriptions, not method signatures
69	- Indent sub-steps under their parent action
70
71	The goal is to outline the system concisely — show how it behaves, not how the code is structured. A reader should be able to understand the full lifecycle from the diagram alone.
72
73	See the example in `example.md` for the expected style and level of detail.
74
75	### 2. Summary
76
77	After the diagram, add three sections in plain English:
78
79	Entry points — every way this flow can be triggered. For each, one sentence describing what triggers it and what it does.
80
81	Branching logic — the conditions that shape the flow. Feature flags, state checks, validations, guard clauses — anything that determines which path is taken.
82
83	Side effects — everything with consequences outside the immediate flow. Jobs, mailers, external API calls, broadcasts, cache writes, state transitions. The things you'd need to know about before touching this code.
84
85	---
86
87	## Tone
88
89	Clear and direct. You're translating, not teaching and not judging. The goal is that they finish with a working mental model of what this code does and how to navigate it. Skip all hedging — if something is unclear in the code itself, say so plainly.

People who liked this also viewed

6 picks

Type

explain

15stars1forks

View on GitHub

How to install explain?

thoughtbot/rails-consultant/explain

$npx -y skills add thoughtbot/rails-consultant --skill explain

Installs into the current project.

Summary

Explain what a piece of code does — a specific file, class, or method in close detail, or a user-facing flow as a concise system overview. What it does and why, not whether it's good.

Files · 1

View on GitHub

SKILL.md

1	## Behavior
2
3	Explain `$ARGUMENTS`. Do the research and deliver the explanation in one pass.
4
5	Determine the mode from the argument:
6
7	- If the argument is a file path, class name, or method — this is a code explanation. Follow the Code Explanation section.
8	- If the argument is a user action, feature, or flow description (e.g. "password reset", "checkout", "authentication") — this is a flow explanation. Follow the Flow Explanation section.
9
10	---
11
12	## Code Explanation
13
14	Start by checking the git history for the file: `git log --oneline -15 <file>` and `git log -1 -p <file>` for the most recent change. Commit messages often reveal the "why" that the code itself doesn't — a bug that was fixed, a refactor that simplified something, a workaround for an external constraint. Note anything that reframes the code before diving into it.
15
16	Then read the code carefully and explain in this order:
17
18	### 1. What it does — in one paragraph
19
20	Plain English. No jargon, no code. Describe what this code accomplishes from the outside — what goes in, what comes out, what changes as a result. Write it the way you'd explain it to the client who asked for the feature.
21
22	### 2. How it does it — walking through the logic
23
24	Narrate the code path in plain English, step by step. For each meaningful chunk:
25
26	- What is this step doing?
27	- Why is it doing it here, in this order?
28	- What would break if it wasn't here?
29
30	Don't narrate every line — skip the obvious. Focus on the parts that require interpretation.
31
32	### 3. Patterns and conventions in use
33
34	Name the Rails, Ruby, or design patterns this code is using — and why they appear here. Examples:
35
36	- "This is a service object following the thoughtbot pattern — one public `call` method, one responsibility"
37	- "This is using `delegate` to avoid Law of Demeter violations"
38	- "This callback is doing what's normally done in a service object — worth noting"
39	- "This is a query object extracting complex AR logic out of the model"
40
41	If the code is using a pattern poorly or unexpectedly, name that too — neutrally. This isn't a review, but understanding requires knowing when something is off-label.
42
43	### 4. What to watch out for
44
45	Any non-obvious behaviour, implicit dependencies, or things that would surprise someone maintaining this code. Not a critique — just "here's what you'd need to know to work safely in this area."
46
47	---
48
49	## Flow Explanation
50
51	Start with the Rails router. Locate the route(s) that correspond to the described flow. From each entry point, trace the execution path through the codebase — controllers, service objects, models, callbacks, jobs, mailers. Follow both success and failure paths.
52
53	Then deliver the explanation in two parts: a diagram and a summary.
54
55	### 1. Diagram
56
57	Render a concise visual flowchart of the system using box-drawing characters. The diagram should show:
58
59	- States and transitions — the lifecycle, not the method calls
60	- Decision points — where the flow branches
61	- Key actions — what happens at each step, described in plain English
62	- Terminal states — where the flow ends
63
64	Conventions:
65
66	- Box-drawing characters for structure: `┌─┐`, `│`, `├──`, `└──`, `▼`, `◄`
67	- Decision points as plain text with branches: `YES` / `NO`
68	- Actions as concise descriptions, not method signatures
69	- Indent sub-steps under their parent action
70
71	The goal is to outline the system concisely — show how it behaves, not how the code is structured. A reader should be able to understand the full lifecycle from the diagram alone.
72
73	See the example in `example.md` for the expected style and level of detail.
74
75	### 2. Summary
76
77	After the diagram, add three sections in plain English:
78
79	Entry points — every way this flow can be triggered. For each, one sentence describing what triggers it and what it does.
80
81	Branching logic — the conditions that shape the flow. Feature flags, state checks, validations, guard clauses — anything that determines which path is taken.
82
83	Side effects — everything with consequences outside the immediate flow. Jobs, mailers, external API calls, broadcasts, cache writes, state transitions. The things you'd need to know about before touching this code.
84
85	---
86
87	## Tone
88
89	Clear and direct. You're translating, not teaching and not judging. The goal is that they finish with a working mental model of what this code does and how to navigate it. Skip all hedging — if something is unclear in the code itself, say so plainly.

People who liked this also viewed

6 picks

Type