introspect

Name: introspect
Author: softspark

161stars21forks

How to install introspect?

softspark/ai-toolkit/introspect

$npx -y skills add softspark/ai-toolkit --skill introspect

Installs into the current project.

Summary

Agent self-debugging and recovery. Use when stuck in loops, making repeated errors, or quality degrades. Triggers: introspect, self-debug, stuck, loop, why failing.

Files · 1

View on GitHub

SKILL.md

1	# Agent Self-Debugging
2
3	$ARGUMENTS
4
5	Structured self-analysis for when the agent is stuck, looping, or producing degraded output.
6
7	---
8
9	## Step 1: Capture Failure State
10
11	Before diagnosing, gather the facts. Answer each question concisely:
12
13	\| Question \| Answer \|
14	\|----------\|--------\|
15	\| Last goal/task \| What was the agent trying to accomplish? \|
16	\| Actions taken \| List the last 3-5 actions in order \|
17	\| Errors or unexpected results \| What went wrong? What was expected vs actual? \|
18	\| Attempt count \| How many times has this been tried? \|
19	\| Time spent \| Rough estimate of effort so far \|
20
21	---
22
23	## Step 2: Classify the Failure Pattern
24
25	Identify which pattern matches the current situation:
26
27	\| Pattern \| Symptoms \| Common Cause \|
28	\|---------\|----------\|--------------\|
29	\| Loop \| Same action repeated 3+ times \| Missing exit condition, wrong approach \|
30	\| Drift \| Actions diverge from original goal \| Lost context, scope creep \|
31	\| Assumption Error \| Working with wrong mental model \| Didn't read code, assumed behavior \|
32	\| Tool Misuse \| Wrong tool for the job \| Grep when should Read, Bash when should Edit \|
33	\| Context Overflow \| Forgetting earlier findings \| Too much context, need compaction \|
34	\| Wrong Abstraction \| Over-engineering simple task \| Premature abstraction, YAGNI violation \|
35	\| Missing Information \| Can't proceed without data \| Need to ask user, read more code \|
36
37	Pick the single best match. If multiple apply, pick the root cause pattern (the one that, if fixed, would resolve the others).
38
39	---
40
41	## Step 3: Diagnose Root Cause
42
43	Answer these three questions:
44
45	1. What assumption was wrong? — Identify the specific belief that led to failure.
46	2. What information was missing? — What would have prevented the failure if known earlier?
47	3. What would a fresh start look like? — If starting over with current knowledge, what would the first action be?
48
49	---
50
51	## Step 4: Select Recovery Action
52
53	Choose the smallest recovery action and apply the smallest possible fix — do not restart from scratch unless absolutely necessary:
54
55	\| Pattern \| Recovery Action \|
56	\|---------\|----------------\|
57	\| Loop \| Stop. Change approach entirely — different tool, different strategy, different angle. \|
58	\| Drift \| Re-read the original user request verbatim. Reset scope to exactly what was asked. \|
59	\| Assumption Error \| Read the actual code, file, or docs. Do not guess. Verify the mental model. \|
60	\| Tool Misuse \| Switch to the correct tool. Read instead of Grep for full context. Edit instead of Bash for file changes. \|
61	\| Context Overflow \| Summarize all findings so far in 5 bullet points. Compact and continue. \|
62	\| Wrong Abstraction \| Delete the abstraction. Do the simplest, most direct thing that works. \|
63	\| Missing Information \| Ask the user exactly ONE specific question. Do not guess. \|
64
65	---
66
67	## Step 5: Produce the Introspection Report
68
69	Output exactly this format:
70
71	```markdown
72	## Introspection Report
73
74	Pattern: [Loop\|Drift\|Assumption Error\|Tool Misuse\|Context Overflow\|Wrong Abstraction\|Missing Information]
75	Root Cause: [1-2 sentence diagnosis]
76	Recovery Action: [Specific next step]
77	Confidence: [HIGH\|MEDIUM\|LOW]
78
79	### What happened
80	[Brief timeline of actions taken — 3-5 bullet points max]
81
82	### What went wrong
83	[Specific diagnosis — what assumption failed, what was missed]
84
85	### What to do next
86	[ONE concrete action — not a plan, a single next step]
87	```
88
89	---
90
91	## Rules
92
93	- MUST name a specific failure pattern (Loop / Drift / Assumption Error / Tool Misuse / Context Overflow / Wrong Abstraction / Missing Information) — vague self-diagnosis is useless
94	- MUST ground the diagnosis in concrete evidence (action traces, error messages, tool outputs) — not in feelings or hunches
95	- NEVER retry the exact same action. If it failed once, it will fail again. Change something.
96	- NEVER continue a loop "hoping it will work this time". Hope is not a strategy.
97	- CRITICAL: after 3 failed attempts, escalate to the user with a concrete report of what was tried, what failed, and what you need — do not keep flailing
98	- MANDATORY: the recovery action is ONE concrete next step, not a multi-phase plan. If you need a plan, use `/plan`.
99
100	## Gotchas
101
102	- "Introspection" invoked mid-task can itself become a procrastination loop — spending effort diagnosing instead of acting. If the report takes longer to write than the next concrete action, skip the report and just change approach.
103	- Context overflow is often invisible from inside the session — the model cannot reliably detect its own forgetting. External signals (user frustration, repeated explanation

People who liked this also viewed

6 picks

Type

find-skillsHelps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skSkillsJul 20262.6M27k
grill-meA relentless interview to sharpen a plan or design.SkillsJul 2026633k182k
vercel-react-best-practicesVercel's official collection of agent skillsSkillsJul 2026573k29k
improve-codebase-architectureScan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.SkillsJul 2026522k182k
setup-matt-pocock-skillsConfigure this repo for the engineering skills — set up its issue tracker, triage label vocabulary, and domain doc layout. Run once before first use of the other engineering skills.SkillsJul 2026454k182k
triageMove issues and external PRs through a state machine of triage roles — categorise, verify, grill if needed, and write agent-ready briefs.SkillsJul 2026424k182k

introspect

161stars21forks

View on GitHub

How to install introspect?

softspark/ai-toolkit/introspect

$npx -y skills add softspark/ai-toolkit --skill introspect

Installs into the current project.

Summary

Agent self-debugging and recovery. Use when stuck in loops, making repeated errors, or quality degrades. Triggers: introspect, self-debug, stuck, loop, why failing.

Files · 1

View on GitHub

SKILL.md

1	# Agent Self-Debugging
2
3	$ARGUMENTS
4
5	Structured self-analysis for when the agent is stuck, looping, or producing degraded output.
6
7	---
8
9	## Step 1: Capture Failure State
10
11	Before diagnosing, gather the facts. Answer each question concisely:
12
13	\| Question \| Answer \|
14	\|----------\|--------\|
15	\| Last goal/task \| What was the agent trying to accomplish? \|
16	\| Actions taken \| List the last 3-5 actions in order \|
17	\| Errors or unexpected results \| What went wrong? What was expected vs actual? \|
18	\| Attempt count \| How many times has this been tried? \|
19	\| Time spent \| Rough estimate of effort so far \|
20
21	---
22
23	## Step 2: Classify the Failure Pattern
24
25	Identify which pattern matches the current situation:
26
27	\| Pattern \| Symptoms \| Common Cause \|
28	\|---------\|----------\|--------------\|
29	\| Loop \| Same action repeated 3+ times \| Missing exit condition, wrong approach \|
30	\| Drift \| Actions diverge from original goal \| Lost context, scope creep \|
31	\| Assumption Error \| Working with wrong mental model \| Didn't read code, assumed behavior \|
32	\| Tool Misuse \| Wrong tool for the job \| Grep when should Read, Bash when should Edit \|
33	\| Context Overflow \| Forgetting earlier findings \| Too much context, need compaction \|
34	\| Wrong Abstraction \| Over-engineering simple task \| Premature abstraction, YAGNI violation \|
35	\| Missing Information \| Can't proceed without data \| Need to ask user, read more code \|
36
37	Pick the single best match. If multiple apply, pick the root cause pattern (the one that, if fixed, would resolve the others).
38
39	---
40
41	## Step 3: Diagnose Root Cause
42
43	Answer these three questions:
44
45	1. What assumption was wrong? — Identify the specific belief that led to failure.
46	2. What information was missing? — What would have prevented the failure if known earlier?
47	3. What would a fresh start look like? — If starting over with current knowledge, what would the first action be?
48
49	---
50
51	## Step 4: Select Recovery Action
52
53	Choose the smallest recovery action and apply the smallest possible fix — do not restart from scratch unless absolutely necessary:
54
55	\| Pattern \| Recovery Action \|
56	\|---------\|----------------\|
57	\| Loop \| Stop. Change approach entirely — different tool, different strategy, different angle. \|
58	\| Drift \| Re-read the original user request verbatim. Reset scope to exactly what was asked. \|
59	\| Assumption Error \| Read the actual code, file, or docs. Do not guess. Verify the mental model. \|
60	\| Tool Misuse \| Switch to the correct tool. Read instead of Grep for full context. Edit instead of Bash for file changes. \|
61	\| Context Overflow \| Summarize all findings so far in 5 bullet points. Compact and continue. \|
62	\| Wrong Abstraction \| Delete the abstraction. Do the simplest, most direct thing that works. \|
63	\| Missing Information \| Ask the user exactly ONE specific question. Do not guess. \|
64
65	---
66
67	## Step 5: Produce the Introspection Report
68
69	Output exactly this format:
70
71	```markdown
72	## Introspection Report
73
74	Pattern: [Loop\|Drift\|Assumption Error\|Tool Misuse\|Context Overflow\|Wrong Abstraction\|Missing Information]
75	Root Cause: [1-2 sentence diagnosis]
76	Recovery Action: [Specific next step]
77	Confidence: [HIGH\|MEDIUM\|LOW]
78
79	### What happened
80	[Brief timeline of actions taken — 3-5 bullet points max]
81
82	### What went wrong
83	[Specific diagnosis — what assumption failed, what was missed]
84
85	### What to do next
86	[ONE concrete action — not a plan, a single next step]
87	```
88
89	---
90
91	## Rules
92
93	- MUST name a specific failure pattern (Loop / Drift / Assumption Error / Tool Misuse / Context Overflow / Wrong Abstraction / Missing Information) — vague self-diagnosis is useless
94	- MUST ground the diagnosis in concrete evidence (action traces, error messages, tool outputs) — not in feelings or hunches
95	- NEVER retry the exact same action. If it failed once, it will fail again. Change something.
96	- NEVER continue a loop "hoping it will work this time". Hope is not a strategy.
97	- CRITICAL: after 3 failed attempts, escalate to the user with a concrete report of what was tried, what failed, and what you need — do not keep flailing
98	- MANDATORY: the recovery action is ONE concrete next step, not a multi-phase plan. If you need a plan, use `/plan`.
99
100	## Gotchas
101
102	- "Introspection" invoked mid-task can itself become a procrastination loop — spending effort diagnosing instead of acting. If the report takes longer to write than the next concrete action, skip the report and just change approach.
103	- Context overflow is often invisible from inside the session — the model cannot reliably detect its own forgetting. External signals (user frustration, repeated explanation

People who liked this also viewed

6 picks

Type