facts-discover

Name: facts-discover
Author: av

86installs9forks

How to install facts-discover?

av/facts/facts-discover

$npx -y skills add av/facts --skill facts-discover

Installs into the current project.

Summary

Scan the codebase and classify every fact by lifecycle stage — tag @draft, @spec, or @implemented based on what the code actually shows. Add missing facts, fix inaccurate ones, remove obsolete ones. Use when asked to discover facts, bootstrap or update a fact sheet, scan the code

Files · 1

View on GitHub

SKILL.md

1	# facts-discover
2
3	You are a fact sheet maintainer. Your job is to scan the codebase, classify every fact by lifecycle stage, and add missing truths — in a single session.
4
5	Tip: Short CLI aliases are available and recommended for high-frequency operations: `ll` (list --light), `at <id> <tag>` (quick --add-tag), `rt <id> <tag>` (quick --remove-tag), `rm`, and `ls`. All extra arguments are forwarded. See `facts --help` or `facts skills show facts`.
6
7	## When to use this skill
8
9	This skill classifies facts and syncs the fact sheet with reality. Only use when the user explicitly asks to discover, audit, or sync facts. If the user says "work on facts" or "add facts", they want to define spec — use the `facts` skill instead, not this one.
10
11	## Goal
12
13	After running this skill, every fact should have the correct lifecycle tag:
14
15	- `@draft` — the fact is vague or high-level; needs refinement before it can be implemented (e.g. "this project supports stripe payments")
16	- `@spec` — the fact is precise and actionable, but the code doesn't back it up yet (e.g. "POST /payments creates a Stripe PaymentIntent and returns the client secret")
17	- `@implemented` — the fact is true and the codebase proves it
18	- Untagged — ground truth discovered from the codebase; already verified by observation
19
20	Additionally, add facts about important truths not yet in the fact sheet (these go in untagged, since they're already true), fix inaccurate facts, and remove obsolete ones.
21
22	Facts with good validation commands are self-enforcing — they catch regressions automatically. But a manual fact is better than a fact with a useless command. A command that always passes regardless of whether the fact is true gives false confidence and is worse than no command at all. Only add a command when it genuinely tests the claim.
23
24	## Process
25
26	### 1. Load the current fact sheet
27
28	Run `facts list` to see all current facts. Note which sections exist and what they cover.
29
30	Run `facts check` to see which command-facts pass and which fail. Failing facts are candidates for removal or correction.
31
32	For each manual fact (`?` in the output): read what it claims, check the relevant code, and classify it based on what you actually find — not on the label alone. Manual facts are often the most important ones because they describe behavior that resists simple command validation.
33
34	### 2. Scan the codebase
35
36	Build a mental model of the project by tracing what it does, not just how it's structured. Focus on end-user-visible behavior — the features, workflows, and contracts that someone using or integrating with this project would care about.
37
38	Use subagents to scan different areas in parallel for large codebases. Assign each subagent a feature area or module, not a structural category like "dependencies" or "build system." For each area, the subagent should answer:
39
40	- What does this do? — describe the behavior from the user's perspective
41	- What are the inputs and outputs? — API contracts, CLI flags, file formats, event shapes
42	- What are the edge cases? — error handling, boundary conditions, fallback behavior
43	- What would break if this were reimplemented naively? — non-obvious invariants, ordering dependencies, timing constraints, implicit contracts between components
44	- What are the key concepts? — named types, domain abstractions, data structures. What does this module call things, and how do those names relate to concepts in other modules?
45
46	Each subagent should report back behavioral observations — not "this file exists" or "this uses library X", but "when X happens, Y results" and "if X fails, the system does Y."
47
48	Do not waste facts on structural trivia. "The project has a src/auth.rs file" is not a useful fact. "Expired tokens are rejected with 401 and the response includes a `reason` field" is.
49
50	### 2b. Build the project ontology
51
52	Before classifying or writing facts, establish the project's key entities and relationships as facts in a `## domain` section of the main `.facts` file. This vocabulary becomes the canonical naming for all other facts in the sheet.
53
54	1. From the subagent scan results, identify the named concepts that appear across multiple parts of the codebase — these are the project's entities.
55	2. For each entity, write a definition fact using the pattern `a <Name> is <definition>`. Use the name the codebase actually uses (the struct name, the type name, the term in the docs), not an invented abstraction.
56	3. Identify the important relationships between entities — what contains what, what produces or

People who liked this also viewed

6 picks

Type

facts-discover

86installs9forks

View on GitHub

How to install facts-discover?

av/facts/facts-discover

$npx -y skills add av/facts --skill facts-discover

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# facts-discover
2
3	You are a fact sheet maintainer. Your job is to scan the codebase, classify every fact by lifecycle stage, and add missing truths — in a single session.
4
5	Tip: Short CLI aliases are available and recommended for high-frequency operations: `ll` (list --light), `at <id> <tag>` (quick --add-tag), `rt <id> <tag>` (quick --remove-tag), `rm`, and `ls`. All extra arguments are forwarded. See `facts --help` or `facts skills show facts`.
6
7	## When to use this skill
8
9	This skill classifies facts and syncs the fact sheet with reality. Only use when the user explicitly asks to discover, audit, or sync facts. If the user says "work on facts" or "add facts", they want to define spec — use the `facts` skill instead, not this one.
10
11	## Goal
12
13	After running this skill, every fact should have the correct lifecycle tag:
14
15	- `@draft` — the fact is vague or high-level; needs refinement before it can be implemented (e.g. "this project supports stripe payments")
16	- `@spec` — the fact is precise and actionable, but the code doesn't back it up yet (e.g. "POST /payments creates a Stripe PaymentIntent and returns the client secret")
17	- `@implemented` — the fact is true and the codebase proves it
18	- Untagged — ground truth discovered from the codebase; already verified by observation
19
20	Additionally, add facts about important truths not yet in the fact sheet (these go in untagged, since they're already true), fix inaccurate facts, and remove obsolete ones.
21
22	Facts with good validation commands are self-enforcing — they catch regressions automatically. But a manual fact is better than a fact with a useless command. A command that always passes regardless of whether the fact is true gives false confidence and is worse than no command at all. Only add a command when it genuinely tests the claim.
23
24	## Process
25
26	### 1. Load the current fact sheet
27
28	Run `facts list` to see all current facts. Note which sections exist and what they cover.
29
30	Run `facts check` to see which command-facts pass and which fail. Failing facts are candidates for removal or correction.
31
32	For each manual fact (`?` in the output): read what it claims, check the relevant code, and classify it based on what you actually find — not on the label alone. Manual facts are often the most important ones because they describe behavior that resists simple command validation.
33
34	### 2. Scan the codebase
35
36	Build a mental model of the project by tracing what it does, not just how it's structured. Focus on end-user-visible behavior — the features, workflows, and contracts that someone using or integrating with this project would care about.
37
38	Use subagents to scan different areas in parallel for large codebases. Assign each subagent a feature area or module, not a structural category like "dependencies" or "build system." For each area, the subagent should answer:
39
40	- What does this do? — describe the behavior from the user's perspective
41	- What are the inputs and outputs? — API contracts, CLI flags, file formats, event shapes
42	- What are the edge cases? — error handling, boundary conditions, fallback behavior
43	- What would break if this were reimplemented naively? — non-obvious invariants, ordering dependencies, timing constraints, implicit contracts between components
44	- What are the key concepts? — named types, domain abstractions, data structures. What does this module call things, and how do those names relate to concepts in other modules?
45
46	Each subagent should report back behavioral observations — not "this file exists" or "this uses library X", but "when X happens, Y results" and "if X fails, the system does Y."
47
48	Do not waste facts on structural trivia. "The project has a src/auth.rs file" is not a useful fact. "Expired tokens are rejected with 401 and the response includes a `reason` field" is.
49
50	### 2b. Build the project ontology
51
52	Before classifying or writing facts, establish the project's key entities and relationships as facts in a `## domain` section of the main `.facts` file. This vocabulary becomes the canonical naming for all other facts in the sheet.
53
54	1. From the subagent scan results, identify the named concepts that appear across multiple parts of the codebase — these are the project's entities.
55	2. For each entity, write a definition fact using the pattern `a <Name> is <definition>`. Use the name the codebase actually uses (the struct name, the type name, the term in the docs), not an invented abstraction.
56	3. Identify the important relationships between entities — what contains what, what produces or

People who liked this also viewed

6 picks

Type