introspection

Name: introspection
Author: tkellogg

83stars19forks

How to install introspection?

tkellogg/open-strix/introspection

$npx -y skills add tkellogg/open-strix --skill introspection

Installs into the current project.

Summary

Diagnose agent behavior using event logs, journal history, and scheduler state. Use when you need to understand why something went wrong, review your own patterns, audit scheduled jobs, or debug communication issues. Do not use for one-off messaging or memory management (use the

Files · 1

View on GitHub

SKILL.md

1	# Introspection
2
3	You are a stateful agent. Your behavior leaves traces in structured logs. This skill
4	teaches you to read those traces to diagnose problems, understand your own patterns,
5	and improve.
6
7	## Source of Truth Hierarchy
8
9	1. `logs/events.jsonl` — Ground truth. Every tool call, error, and scheduler
10	event is recorded here with timestamps and session IDs.
11	2. `logs/journal.jsonl` — Your interpretation of what happened. Useful for
12	intent and predictions, but it's narrative, not fact.
13	3. Discord message history — What was actually sent and received. Use
14	`list_messages` to verify.
15	4. `scheduler.yaml` — Current scheduled job definitions.
16	5. Memory blocks — Your current beliefs about the world. May be stale.
17
18	When sources conflict, trust events > Discord history > journal > memory blocks.
19
20	## Key Log Schemas
21
22	### events.jsonl
23
24	Each line is a JSON object:
25
26	```json
27	{
28	"timestamp": "2026-03-01T12:00:00+00:00",
29	"type": "tool_call",
30	"session_id": "abc123",
31	"tool": "send_message",
32	"channel_id": "123456",
33	"sent": true,
34	"text_preview": "first 300 chars..."
35	}
36	```
37
38	Common event types:
39	- `tool_call` — Any tool invocation (check `tool` field for which one)
40	- `tool_call_error` — A tool that failed (check `error_type`)
41	- `send_message_loop_detected` — Circuit breaker caught repeated messages
42	- `send_message_loop_hard_stop` — Turn terminated for safety
43	- `scheduler_reloaded` — Jobs were reloaded from scheduler.yaml
44	- `scheduler_invalid_job` — A job failed validation
45	- `scheduler_invalid_cron` — Bad cron expression
46	- `scheduler_invalid_time` — Bad time_of_day value
47
48	### journal.jsonl
49
50	Each line:
51
52	```json
53	{
54	"timestamp": "2026-03-01T12:00:00+00:00",
55	"session_id": "abc123",
56	"channel_id": "123456",
57	"user_wanted": "what the human asked for",
58	"agent_did": "what you actually did",
59	"predictions": "what you think will happen next"
60	}
61	```
62
63	### scheduler.yaml
64
65	```yaml
66	jobs:
67	- name: my-job
68	prompt: "Do the thing"
69	cron: "0 /2 * *" # OR time_of_day, not both
70	channel_id: "123456" # optional
71	```
72
73	Cron expressions are evaluated in UTC. `time_of_day` is `HH:MM` in UTC.
74
75	## How to Query Events
76
77	### With jq (preferred)
78
79	```bash
80	# Last 20 events
81	tail -n 20 logs/events.jsonl \| jq .
82
83	# All errors in the last session
84	jq -s 'sort_by(.timestamp) \| group_by(.session_id) \| last \| map(select(.type \| test("error")))' logs/events.jsonl
85
86	# All send_message calls in a session
87	jq -s 'map(select(.session_id == "SESSION_ID" and .tool == "send_message"))' logs/events.jsonl
88
89	# Events by type, counted
90	jq -s 'group_by(.type) \| map({type: .[0].type, count: length}) \| sort_by(-.count)' logs/events.jsonl
91
92	# Scheduler events only
93	jq -s 'map(select(.type \| startswith("scheduler")))' logs/events.jsonl
94
95	# Find sessions with errors
96	jq -s '[.[] \| select(.type \| test("error"))] \| group_by(.session_id) \| map({session: .[0].session_id, errors: length}) \| sort_by(-.errors)' logs/events.jsonl
97	```
98
99	### With Python (if jq unavailable)
100
101	```bash
102	uv run python - <<'PY'
103	import json
104	from pathlib import Path
105	from collections import Counter
106
107	events = [json.loads(line) for line in Path("logs/events.jsonl").read_text().splitlines() if line.strip()]
108	type_counts = Counter(e.get("type", "unknown") for e in events)
109	for t, c in type_counts.most_common(20):
110	print(f"{c:>6} {t}")
111	PY
112	```
113
114	## Cross-Referencing with Memory Skill
115
116	The memory skill (`/.open_strix_builtin_skills/memory/SKILL.md`) covers:
117	- When and how to write memory blocks — criteria for block vs file storage
118	- Maintenance — block size monitoring, pruning, file frequency analysis
119	- File organization — cross-references between blocks and state files
120
121	Use introspection to find problems. Use memory to fix the persistent ones (update
122	blocks, reorganize files, add cross-references).
123
124	The file frequency report (`/.open_strix_builtin_skills/scripts/file_frequency_report.py`)
125	bridges both skills — it reads events.jsonl to find which files you access most,
126	informing both debugging (are you reading the same file repeatedly?) and memory
127	optimization (should hot files become blocks?).
128
129	## Patterns That Consume Introspection
130
131	The `patterns/` skill includes several pattern files that explicitly call introspection
132	as the diagnostic step. Reach for these when introspection has surfaced the what
133	and you need the how-to-fix shape:
134
135	- `patterns/circuit-breaker.md` — when you're stuck in a loop, introspection
136	reveals the loop in `events.jsonl`; circuit-breaker is the discipline of stopping and
137	what to do next.
138	- `patterns/try-harder.md` — when behavior keeps drifting, introspection finds the

People who liked this also viewed

6 picks

Type

introspection

83stars19forks

View on GitHub

How to install introspection?

tkellogg/open-strix/introspection

$npx -y skills add tkellogg/open-strix --skill introspection

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Introspection
2
3	You are a stateful agent. Your behavior leaves traces in structured logs. This skill
4	teaches you to read those traces to diagnose problems, understand your own patterns,
5	and improve.
6
7	## Source of Truth Hierarchy
8
9	1. `logs/events.jsonl` — Ground truth. Every tool call, error, and scheduler
10	event is recorded here with timestamps and session IDs.
11	2. `logs/journal.jsonl` — Your interpretation of what happened. Useful for
12	intent and predictions, but it's narrative, not fact.
13	3. Discord message history — What was actually sent and received. Use
14	`list_messages` to verify.
15	4. `scheduler.yaml` — Current scheduled job definitions.
16	5. Memory blocks — Your current beliefs about the world. May be stale.
17
18	When sources conflict, trust events > Discord history > journal > memory blocks.
19
20	## Key Log Schemas
21
22	### events.jsonl
23
24	Each line is a JSON object:
25
26	```json
27	{
28	"timestamp": "2026-03-01T12:00:00+00:00",
29	"type": "tool_call",
30	"session_id": "abc123",
31	"tool": "send_message",
32	"channel_id": "123456",
33	"sent": true,
34	"text_preview": "first 300 chars..."
35	}
36	```
37
38	Common event types:
39	- `tool_call` — Any tool invocation (check `tool` field for which one)
40	- `tool_call_error` — A tool that failed (check `error_type`)
41	- `send_message_loop_detected` — Circuit breaker caught repeated messages
42	- `send_message_loop_hard_stop` — Turn terminated for safety
43	- `scheduler_reloaded` — Jobs were reloaded from scheduler.yaml
44	- `scheduler_invalid_job` — A job failed validation
45	- `scheduler_invalid_cron` — Bad cron expression
46	- `scheduler_invalid_time` — Bad time_of_day value
47
48	### journal.jsonl
49
50	Each line:
51
52	```json
53	{
54	"timestamp": "2026-03-01T12:00:00+00:00",
55	"session_id": "abc123",
56	"channel_id": "123456",
57	"user_wanted": "what the human asked for",
58	"agent_did": "what you actually did",
59	"predictions": "what you think will happen next"
60	}
61	```
62
63	### scheduler.yaml
64
65	```yaml
66	jobs:
67	- name: my-job
68	prompt: "Do the thing"
69	cron: "0 /2 * *" # OR time_of_day, not both
70	channel_id: "123456" # optional
71	```
72
73	Cron expressions are evaluated in UTC. `time_of_day` is `HH:MM` in UTC.
74
75	## How to Query Events
76
77	### With jq (preferred)
78
79	```bash
80	# Last 20 events
81	tail -n 20 logs/events.jsonl \| jq .
82
83	# All errors in the last session
84	jq -s 'sort_by(.timestamp) \| group_by(.session_id) \| last \| map(select(.type \| test("error")))' logs/events.jsonl
85
86	# All send_message calls in a session
87	jq -s 'map(select(.session_id == "SESSION_ID" and .tool == "send_message"))' logs/events.jsonl
88
89	# Events by type, counted
90	jq -s 'group_by(.type) \| map({type: .[0].type, count: length}) \| sort_by(-.count)' logs/events.jsonl
91
92	# Scheduler events only
93	jq -s 'map(select(.type \| startswith("scheduler")))' logs/events.jsonl
94
95	# Find sessions with errors
96	jq -s '[.[] \| select(.type \| test("error"))] \| group_by(.session_id) \| map({session: .[0].session_id, errors: length}) \| sort_by(-.errors)' logs/events.jsonl
97	```
98
99	### With Python (if jq unavailable)
100
101	```bash
102	uv run python - <<'PY'
103	import json
104	from pathlib import Path
105	from collections import Counter
106
107	events = [json.loads(line) for line in Path("logs/events.jsonl").read_text().splitlines() if line.strip()]
108	type_counts = Counter(e.get("type", "unknown") for e in events)
109	for t, c in type_counts.most_common(20):
110	print(f"{c:>6} {t}")
111	PY
112	```
113
114	## Cross-Referencing with Memory Skill
115
116	The memory skill (`/.open_strix_builtin_skills/memory/SKILL.md`) covers:
117	- When and how to write memory blocks — criteria for block vs file storage
118	- Maintenance — block size monitoring, pruning, file frequency analysis
119	- File organization — cross-references between blocks and state files
120
121	Use introspection to find problems. Use memory to fix the persistent ones (update
122	blocks, reorganize files, add cross-references).
123
124	The file frequency report (`/.open_strix_builtin_skills/scripts/file_frequency_report.py`)
125	bridges both skills — it reads events.jsonl to find which files you access most,
126	informing both debugging (are you reading the same file repeatedly?) and memory
127	optimization (should hot files become blocks?).
128
129	## Patterns That Consume Introspection
130
131	The `patterns/` skill includes several pattern files that explicitly call introspection
132	as the diagnostic step. Reach for these when introspection has surfaced the what
133	and you need the how-to-fix shape:
134
135	- `patterns/circuit-breaker.md` — when you're stuck in a loop, introspection
136	reveals the loop in `events.jsonl`; circuit-breaker is the discipline of stopping and
137	what to do next.
138	- `patterns/try-harder.md` — when behavior keeps drifting, introspection finds the

People who liked this also viewed

6 picks

Type