linear-walkthrough

Name: linear-walkthrough
Author: rianvdm

15stars4forks

How to install linear-walkthrough?

rianvdm/product-ai-public/linear-walkthrough

$npx -y skills add rianvdm/product-ai-public --skill linear-walkthrough

Installs into the current project.

Summary

Generates a linear, narrative walkthrough of source material — code, documents, architecture diagrams, meeting notes, Jira tickets, or any combination. Produces a step-by-step guide that explains logic, purpose, and connections between components in a readable sequence. Use when

Files · 1

View on GitHub

SKILL.md

1	# Linear Walkthrough
2
3	You generate linear walkthroughs — narrative documents that explain the logic and implementation of a system, codebase, document, or concept, step by step.
4
5	A walkthrough is not a reference document or a summary. It is a guided tour: it takes the reader from the beginning to the end, building understanding progressively, with each section setting up the next.
6
7	## Before You Start
8
9	Clarify two things — ask if not obvious from context:
10
11	### 1. Audience
12	- Product / non-senior technical: Focus on what and why. Use analogies. Explain jargon when it appears. Keep implementation detail light unless it directly clarifies intent. Think: "would a smart PM who codes a little follow this?"
13	- Engineering / senior technical: Full detail. Implementation specifics, edge cases, architectural decisions, tradeoffs.
14	- Mixed or unknown: Default to PM-level narrative, with optional "Under the Hood" callout blocks for deeper technical content that more technical readers can explore.
15
16	### 2. Intent / downstream use
17	Why is this walkthrough being created? This shapes depth and emphasis:
18
19	\| Intent \| Emphasis \|
20	\|---\|---\|
21	\| "I'm learning this" \| Breadth-first, context-heavy, analogies welcome \|
22	\| "I need to explain this to my team" \| Narrative-first, minimal assumed knowledge \|
23	\| "I'm preparing documentation" \| Precision matters, include edge cases \|
24	\| "I want to build a tutorial from this" \| Modular sections, each concept clearly labelled and self-contained \|
25
26	If you're not sure, ask. If the user doesn't know either, default to "learning" mode and note the assumption.
27
28	## Intake
29
30	Source material may be any combination of:
31	- Code files or repositories
32	- Product documents, PRDs, TDDs
33	- Architecture diagrams or written descriptions
34	- Meeting notes or transcripts
35	- Jira tickets or task lists
36	- A verbal description of a concept
37
38	For code: extract content dynamically using shell commands rather than writing from memory — this prevents hallucinating implementation details that aren't there:
39
40	```bash
41	cat path/to/file.py
42	sed -n '10,40p' path/to/file.py # specific line range
43	grep -n "def " path/to/file.py # find function definitions
44	```
45
46	If source material is incomplete or partially provided, flag the gaps before writing. Don't silently fill in missing detail — make your assumptions visible.
47
48	## Survey Before You Walk
49
50	Before writing, take stock of what you have:
51
52	1. Inventory the key components (files, sections, concepts, modules, decisions)
53	2. Find the entry point — where does understanding naturally start? (Often not where the code starts.)
54	3. Determine reading order — not alphabetical or file order, but the sequence that builds understanding progressively
55	4. Note uncertainties — anything ambiguous, missing, or that you'd need to guess about
56
57	Share the outline with the user if the material is complex or unfamiliar, so they can redirect before you invest in a full draft.
58
59	## Writing the Walkthrough
60
61	Each section should do three things:
62
63	- Orient: Tell the reader what they're about to learn and why it matters in context
64	- Explain: Walk through the logic clearly, at the calibrated depth
65	- Connect: Show how this relates to what came before and what it enables next
66
67	Avoid the temptation to just describe what the code/doc does. The value of a walkthrough is explaining why things are structured the way they are — the intent behind the decisions.
68
69	### Callout Conventions (Obsidian)
70
71	Use these to layer depth without interrupting the narrative:
72
73	```
74	> [!NOTE] Why this matters
75	> Context and motivation — the "why" behind a design choice.
76
77	> [!TIP] Under the Hood
78	> Deeper technical detail. PM-level readers can skip this block.
79
80	> [!WARNING] Uncertainty
81	> When you're making a best guess. State your assumption and confidence.
82
83	> [!EXAMPLE] Analogy
84	> For making abstract concepts concrete for non-technical readers.
85	```
86
87	## Output Format
88
89	Save as a single Obsidian note:
90
91	```
92	---
93	tags: [walkthrough]
94	source: <what was walked through>
95	audience: <pm-level \| engineering \| mixed>
96	intent: <learning \| explanation \| documentation \| tutorial-input>
97	date: <today>
98	---
99
100	# Walkthrough: [Subject]
101
102	## What This Covers
103	<1–2 sentences: what system/concept this covers and why someone would read it>
104
105	## The Lay of the Land
106	<A brief map of the territory — the key c

People who liked this also viewed

6 picks

Type

linear-walkthrough

15stars4forks

View on GitHub

How to install linear-walkthrough?

rianvdm/product-ai-public/linear-walkthrough

$npx -y skills add rianvdm/product-ai-public --skill linear-walkthrough

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Linear Walkthrough
2
3	You generate linear walkthroughs — narrative documents that explain the logic and implementation of a system, codebase, document, or concept, step by step.
4
5	A walkthrough is not a reference document or a summary. It is a guided tour: it takes the reader from the beginning to the end, building understanding progressively, with each section setting up the next.
6
7	## Before You Start
8
9	Clarify two things — ask if not obvious from context:
10
11	### 1. Audience
12	- Product / non-senior technical: Focus on what and why. Use analogies. Explain jargon when it appears. Keep implementation detail light unless it directly clarifies intent. Think: "would a smart PM who codes a little follow this?"
13	- Engineering / senior technical: Full detail. Implementation specifics, edge cases, architectural decisions, tradeoffs.
14	- Mixed or unknown: Default to PM-level narrative, with optional "Under the Hood" callout blocks for deeper technical content that more technical readers can explore.
15
16	### 2. Intent / downstream use
17	Why is this walkthrough being created? This shapes depth and emphasis:
18
19	\| Intent \| Emphasis \|
20	\|---\|---\|
21	\| "I'm learning this" \| Breadth-first, context-heavy, analogies welcome \|
22	\| "I need to explain this to my team" \| Narrative-first, minimal assumed knowledge \|
23	\| "I'm preparing documentation" \| Precision matters, include edge cases \|
24	\| "I want to build a tutorial from this" \| Modular sections, each concept clearly labelled and self-contained \|
25
26	If you're not sure, ask. If the user doesn't know either, default to "learning" mode and note the assumption.
27
28	## Intake
29
30	Source material may be any combination of:
31	- Code files or repositories
32	- Product documents, PRDs, TDDs
33	- Architecture diagrams or written descriptions
34	- Meeting notes or transcripts
35	- Jira tickets or task lists
36	- A verbal description of a concept
37
38	For code: extract content dynamically using shell commands rather than writing from memory — this prevents hallucinating implementation details that aren't there:
39
40	```bash
41	cat path/to/file.py
42	sed -n '10,40p' path/to/file.py # specific line range
43	grep -n "def " path/to/file.py # find function definitions
44	```
45
46	If source material is incomplete or partially provided, flag the gaps before writing. Don't silently fill in missing detail — make your assumptions visible.
47
48	## Survey Before You Walk
49
50	Before writing, take stock of what you have:
51
52	1. Inventory the key components (files, sections, concepts, modules, decisions)
53	2. Find the entry point — where does understanding naturally start? (Often not where the code starts.)
54	3. Determine reading order — not alphabetical or file order, but the sequence that builds understanding progressively
55	4. Note uncertainties — anything ambiguous, missing, or that you'd need to guess about
56
57	Share the outline with the user if the material is complex or unfamiliar, so they can redirect before you invest in a full draft.
58
59	## Writing the Walkthrough
60
61	Each section should do three things:
62
63	- Orient: Tell the reader what they're about to learn and why it matters in context
64	- Explain: Walk through the logic clearly, at the calibrated depth
65	- Connect: Show how this relates to what came before and what it enables next
66
67	Avoid the temptation to just describe what the code/doc does. The value of a walkthrough is explaining why things are structured the way they are — the intent behind the decisions.
68
69	### Callout Conventions (Obsidian)
70
71	Use these to layer depth without interrupting the narrative:
72
73	```
74	> [!NOTE] Why this matters
75	> Context and motivation — the "why" behind a design choice.
76
77	> [!TIP] Under the Hood
78	> Deeper technical detail. PM-level readers can skip this block.
79
80	> [!WARNING] Uncertainty
81	> When you're making a best guess. State your assumption and confidence.
82
83	> [!EXAMPLE] Analogy
84	> For making abstract concepts concrete for non-technical readers.
85	```
86
87	## Output Format
88
89	Save as a single Obsidian note:
90
91	```
92	---
93	tags: [walkthrough]
94	source: <what was walked through>
95	audience: <pm-level \| engineering \| mixed>
96	intent: <learning \| explanation \| documentation \| tutorial-input>
97	date: <today>
98	---
99
100	# Walkthrough: [Subject]
101
102	## What This Covers
103	<1–2 sentences: what system/concept this covers and why someone would read it>
104
105	## The Lay of the Land
106	<A brief map of the territory — the key c

People who liked this also viewed

6 picks

Type