Query

Runs on: local-exec - runs a local script; on a cloud surface I read the results, I do not run it.

This skill retrieves OS nodes for a question by walking markdown files and brain/relations.yaml. It uses plain files only. No vector database, no embeddings, no external service.

Pre-Flight

If core/identity.md does not exist, stop with: Founder OS not set up here. Run /founder-os:setup first.

If brain/relations.yaml is missing, tell the user to run /founder-os:wiki-build first, then continue with keyword search if enough files exist.

If scripts/query.py exists, use it. If not, perform the procedure manually.

Three Modes

The script has three modes for progressive disclosure. Start with index, drill in with timeline, pull specific bodies with full.

1. index (default)

Returns ~10 candidate nodes with ID, path, first heading, decay flag if present, and a 1-line context. Target ~50 tokens per hit. Hard cap 10 hits. Use this on the first call when you do not yet know which entries you need.

Pass the question through the quoted block below, never inside quotes on the command line. Inside double quotes $(...) and backticks still run, and inside single quotes an apostrophe ends the string. Put the question on its own line between the two marker lines, exactly as the user wrote it, with nothing escaped. Every line starts at the left edge with no spaces in front, or bash will not see the end marker:

python scripts/query.py "$(cat <<'FOUNDER_OS_Q_END'
<the user's question, verbatim>
FOUNDER_OS_Q_END
)"

If the question has a line that reads exactly FOUNDER_OS_Q_END, do not run it. Ask the user to rephrase it without that line.

For explicit index mode, write --mode index before the quoted block, on the first line: python scripts/query.py --mode index "$(cat <<'FOUNDER_OS_Q_END'. The other lines stay as above. Flags and their values follow the token rule in .claude/commands/query.md: letters, digits and _ . / , : = - only.

2. timeline

Given an anchor (file slug or brain ID), returns entries within 7 days either side, ordered chronologically. Target ~150 tokens per hit. Hard cap 20 hits. Use after index when you want to see what was happening around a specific node.

python scripts/query.py --mode timeline --anchor brain/flags.md
python scripts/query.py --mode timeline --anchor log-2026-05-07-001

If the anchor is a brain ID, the date is read from the ID itself. If the anchor is a file slug, the date is read from frontmatter (updated: or date:). If neither is present, file mtime is used as a fallback.

Definition: an "entry" in timeline mode is one markdown file (per-file granularity, dated by frontmatter or mtime). Per-heading granularity is parked for a later version.

3. full

Given a comma-separated list of IDs, returns the full body of each entry. No cap, the user explicitly asked for these. Use after timeline (or directly from index) when you want the actual content of a specific entry.

python scripts/query.py --mode full --ids log-2026-05-07-001,log-2026-05-07-002

For each ID the script searches every markdown file in scope and matches the ID either as a frontmatter id: line or as a trailing parenthetical on a heading line (<id>). The body returned is the heading line plus all lines up to the next heading at the same depth or shallower. If no match is found, the output is id <X>: not found and the script continues with the next ID.

Operating against a non-default root

The script accepts --root <path> to point at another Founder OS-style folder, such as a vendored archive or a fixture corpus. Use it when the current shell is outside the folder you want to query. The flag and its path go before the quoted block:

python scripts/query.py --root /path/to/archive "$(cat <<'FOUNDER_OS_Q_END'
outreach stalled
FOUNDER_OS_Q_END
)"

Progressive Flow

Recommended pattern for any non-trivial question:

1. Call index mode with the question. Skim the 10 hits.
2. Pick one slug or ID that looks most relevant.
3. Call timeline mode anchored on that slug to see surrounding context.
4. Call full mode with the specific IDs you want to read end to end.

This keeps token cost low until the user commits to a deeper read.

Manual Procedure (if script is missing)

1. Read brain/relations.yaml.
2. Read the boot files:
   • CLAUDE.md
   • core/identity.md
   • context/priorities.md
   • context/decisions.md
   • rules/operating-rules.md
3. Read brain/patterns.md and brain/flags.md if they exist.
4. Identify candidate nodes by keyword match against the user's question.
5. Walk curated and auto-generated edges up to 3 hops from each candidate.
6. Rank by keyword match, edge count, and recency.
7. Return the top 3 to 5 nodes with the path that connects each result to the question.

Output Formats

index mode

QUERY: <user question>
---
Top results:

1. <node> (id: <id>) [DECAY soon (YYYY-MM-DD)] - <one-line context> - reached via: <path>
2. <node> - <one-line context> - reached via: <path>
...

Recommend reading: <single highest-value node>

timeline mode

TIMELINE: <anchor> (YYYY-MM-DD) +/- 7 days
---

YYYY-MM-DD - <node> (id: <id>)
  <first heading>
  <body lines, capped>

full mode

FULL: id1, id2
---

=== id1 (path) ===
<body block>

Rules

• Read-only. Never write to relations.yaml or any brain file.
• No external dependencies. Pure Python stdlib.
• No embeddings or graph database in v1.7.
• index mode output stays under ~500 tokens total even with a corpus of 1000 markdown files (10-hit cap, 200-char context).