Wiki Query

---
name: wiki-query
description: |
  Search the wiki by topic and read top match(es) into context. Greps only
  frontmatter (title, slug, tags) of wiki/*.md entries using the canonical
  extraction command from context/rules/wiki.md § 6. Splits a multi-word
  topic into space-separated OR terms; an entry matches if ANY term appears
  in the extracted frontmatter. Returns all matching paths to stdout.
  Sub-cap: reads all matches when fewer than 3; reads top 3 (by updated:
  descending) when 3 or more. Empty corpus or no-match exits 0 with a
  human-readable message.
  TRIGGER when: asked to look up a topic in the wiki, "what does the wiki
  say about X", "find wiki entries for X", or when a session wants to
  load previously-compiled knowledge about a topic into context.
argument-hint: "<topic>"
---

# Wiki Query

Search the wiki by topic keyword(s) and load the top matching entry or entries
directly into context. This is Karpathy's "Query + Enhance" operation adapted
for Open Harness: grep frontmatter, rank by recency, read into context.

Query scope is **frontmatter-only** (`title`, `slug`, `tags`). Body text is
deliberately excluded — the frontmatter fields capture the entry's identity
precisely; including body text would make match semantics unpredictable and
slow as the corpus grows.

## When to Use

- `/wiki-query <topic>` when a session needs to recall previously-compiled
  knowledge about a recurring topic (tools, integrations, constraints, key
  concepts).
- Before re-deriving something from scratch — check the wiki first.
- After `/wiki-ingest` lands a new entry, to verify it is queryable.

## When NOT to Use

- **`/wiki-ingest`** — to add or update an entry. `/wiki-query` is read-only.
- **`/wiki-lint`** — to health-check the corpus or regenerate `wiki/README.md`.
- **Direct `grep`** — if you want full-text search including body prose. This
  skill is intentionally frontmatter-only; full-text is out of scope for v1.

## Argument Interface (locked)

```
/wiki-query <topic>
```

`<topic>` is one or more whitespace-separated words. The interface is locked;
do not add flags or positional arguments without editing this SKILL.md.

## Multi-Word OR Semantics

The `<topic>` argument is **split on whitespace** into individual terms. A
wiki entry matches if **ANY** term appears in the frontmatter `title`, `slug`,
or `tags` fields (union of per-term matches, deduplicated). This is OR
semantics, not AND.

Example:

```
/wiki-query github auth
```

This matches entries that contain `github` OR `auth` in their frontmatter —
not only entries that contain both. A result set for `github auth` will include
an entry tagged `[auth, sandbox]` as well as an entry whose title contains
`GitHub Token Workflow Scope`.

Rationale: OR semantics maximize recall on a small corpus. The 3-entry read
cap constrains how much context is loaded regardless of match count.

## Instructions

### 1. Parse the topic argument

```bash
TOPIC="$ARGUMENTS"
```

Split `$TOPIC` on whitespace to produce an array of search terms. Each term
is used independently in the grep step below.

### 2. Collect all wiki entry paths

```bash
HARNESS=/home/sandbox/harness
WIKI_ENTRIES=()
for f in "$HARNESS"/wiki/*.md; do
  [ -f "$f" ] && WIKI_ENTRIES+=("$f")
done
```

This enumerates `wiki/*.md` directly — NOT via `wiki/README.md` (the README
is a human-orientation index regenerated by `/wiki-lint`, not a query backend).
Sub-article files at `wiki/<parent>/<child>.md` are not matched by this glob;
they are scoped for a future iteration.

If no `wiki/*.md` files exist, jump to step 5 (empty result).

### 3. Grep frontmatter for each term — OR semantics

For each entry path, extract its frontmatter using the canonical command locked
in `context/rules/wiki.md` § 6:

```bash
awk '/^---$/{f=!f; next} f{print}' wiki/<slug>.md
```

Then grep the extracted frontmatter for any of the topic terms. An entry is
a match if the grep succeeds for **at least one** term.

Full loop:

```bash
MATCHES=()
for entry in "${WIKI_ENTRIES[@]}"; do
  slug=$(basename "$entry" .md)
  frontmatter=$(awk '/^---$/{f=!f; next} f{print}' "$entry")
  matched=false
  for term in $TOPIC; do
    if echo "$frontmatter" | grep -qi "$term"; then
      matched=true
      break
    fi
  done
  if [ "$matched" = true ]; then
    MATCHES+=("$entry")
  fi
done
```

The grep targets the full extracted frontmatter block — which contains the
`title:`, `slug:`, and `tags:` fields — so all three fields are searched in
a single pass. The grep is case-insensitive (`-i`).

### 4. Print all matching paths to stdout

```bash
for m in "${MATCHES[@]}"; do
  echo "$m"
done
```

All matching `wiki/*.md` file paths are printed, one per line.

### 5. Handle empty results

If `${#MATCHES[@]} -eq 0`:

```bash
echo "No wiki entries matched $TOPIC"
exit 0
```

This is NOT an error condition. Exit status 0 is correct; an empty wiki or a
genuinely absent topic is a normal outcome, not a failure.

### 6. Rank matches by `updated:` descending

Before reading entries into context, sort the match list so the most recently
updated entry is first. Extract the `updated:` field from each match's
frontmatter using the canonical command:

```bash
# Build a sortable list: "<updated-date> <path>"
RANKED=()
for m in "${MATCHES[@]}"; do
  updated=$(awk '/^---$/{f=!f; next} f{print}' "$m" | grep '^updated:' | awk '{print $2}')
  RANKED+=("$updated $m")
done

# Sort descending (most recent first), extract paths
SORTED_PATHS=()
while IFS= read -r line; do
  SORTED_PATHS+=("${line#* }")
done < <(printf '%s\n' "${RANKED[@]}" | sort -r)
```

If an entry has no `updated:` field (malformed frontmatter), it sorts to the
bottom. `/wiki-lint` should surface such entries as a finding.

### 7. Apply the read cap

The read cap is **hardcoded to 3** in v1. Changing the cap requires editing
this SKILL.md — it is NOT configurable via a flag.

```bash
MATCH_COUNT=${#SORTED_PATHS[@]}
CAP=3

if [ "$MATCH_COUNT" -lt "$CAP" ]; then
  # Sub-cap: read ALL matches
  READ_PATHS=("${SORTED_PATHS[@]}")
else
  # At or over cap: read top 3 only
  READ_PATHS=("${SORTED_PATHS[@]:0:$CAP}")
fi
```

Two cases:

| `Match-Count` | Behavior |
|---------------|----------|
| 0 | Print empty-result message; exit 0; read nothing |
| 1 or 2 | Read ALL matches into context (sub-cap: `0 < N < 3`) |
| 3 or more | Read top 3 by `updated:` descending; skip the rest |

### 8. Read matched entries into context

For each path in `READ_PATHS`, read the full `wiki/<slug>.md` file into
context. Each file is read directly — not routed via `wiki/README.md`.

```bash
READ_SLUGS=()
for path in "${READ_PATHS[@]}"; do
  slug=$(basename "$path" .md)
  READ_SLUGS+=("$slug")
  # Read file into context (use the Read tool for each path)
done
```

After reading, summarize what was loaded: list the slugs read, the total match
count, and how many were skipped (if any were above the cap).

### 9. Memory Improvement Protocol

Always run this step regardless of match count. Get UTC time first:

```bash
date -u +%H:%M
TODAY=$(date -u +%Y-%m-%d)
mkdir -p "$HARNESS/memory/$TODAY"
```

Append to `memory/<UTC-date>/log.md`:

```markdown
## /wiki-query -- HH:MM UTC
- **Result**: OP | FAIL
- **Query**: <topic as typed>
- **Match-Count**: <total matches before cap>
- **Read-Slugs**: <comma-separated slugs read into context, or — if zero>
- **Observation**: <one sentence — what was found or why the result set was empty>
```

Field definitions:

| Field | Content |
|-------|---------|
| `Query` | The exact `<topic>` argument as received |
| `Match-Count` | Total frontmatter matches before the read cap is applied |
| `Read-Slugs` | Slugs of entries actually read into context; `—` when `Match-Count = 0` |
| `Result` | `OP` on success (including empty-result); `FAIL` if the skill errored |
| `Observation` | One sentence — e.g., "matched 2 entries on `github`; both read into context" |

Then apply the qualify/improve loop per `context/rules/memory.md`:

- Did the query reveal a gap in the wiki (topic the user expected to find but didn't)?
- Is the absence itself a signal worth noting (e.g., "no entry for X despite repeated re-derivation")?
- If yes, note in the log `Observation` and consider flagging to the orchestrator to run `/wiki-ingest`.

## Extraction Command Reference

The canonical frontmatter extraction command, per `context/rules/wiki.md` § 6:

```bash
awk '/^---$/{f=!f; next} f{print}' wiki/<slug>.md
```

This MUST be the extraction method used in this skill. Deviation from the § 6
command is forbidden — both `/wiki-query` and `/wiki-lint` must use identical
extraction to prevent silent divergence (a match that works in one skill must
work in the other).

## Anti-Patterns

- **Grepping the full file** — `grep <term> wiki/<slug>.md` searches body text
  too, producing false positives from prose mentions of a term. Always extract
  frontmatter first via the § 6 command, then grep the extracted output.
- **Routing through `wiki/README.md`** — the README is a human-orientation
  index regenerated by `/wiki-lint`. Its table format is not a stable query
  backend; use direct `wiki/*.md` file enumeration.
- **AND semantics for multi-word topics** — requiring all terms to match
  reduces recall inappropriately on a small corpus. Use OR: match on any term.
- **Treating empty result as error** — `Match-Count = 0` is a normal outcome
  on a young or sparse corpus. Print the message, exit 0, log it.
- **Hard-coding today's date** in the glob or path — always compute UTC date
  at runtime.
- **Skipping the log** — every invocation appends a log entry, including
  empty-result runs and error runs. No exceptions.

## See Also

- `context/rules/wiki.md` — the locked schema, § 6 (frontmatter extraction canonical command), § 2 (entry schema), § 4 (cross-link convention)
- `/wiki-ingest` — add or update an entry
- `/wiki-lint` — health-check the corpus and regenerate `wiki/README.md`
- `context/rules/memory.md` — Memory Improvement Protocol (MIP) governing the log step