Harness Knowledge Retrieval

Knowledge Retrieval

Purpose

Retrieve durable project knowledge before acting. Use this skill to rebuild context from structured project memory: Feature pages, ADRs, Lessons, specs, plans, Evidence, research, discussions, bug reports, and archive records.

Retrieval reads and judges existing knowledge. It does not build indexes, invent a knowledge service, or write durable memory. Route missing or stale durable memory to harness-knowledge-capture.

Usage telemetry is a narrow exception: when a retrieved Harness document is actually used to change the current task judgment, append one usage event with usage_record.py. This records decision impact, not raw reading.

When To Use

• Starting or resuming non-trivial work.
• Recovering context after handoff, compacted conversation, or interrupted session.
• Finding prior decisions, constraints, rejected approaches, incidents, or validation Evidence.
• Attributing a non-tiny bug, regression, accepted-behavior breakage, or validation failure to an existing Feature or prior fix chain before implementation.
• Searching ADR, Lesson, Feature, spec, plan, discussion, research, bug report, archive, or Evidence records.

When Not To Use

• Tiny local edits where existing project memory cannot change the outcome.
• Creating or updating ADRs, Lessons, Feature pages, Evidence, or handoff notes. Use harness-knowledge-capture.
• Designing a search index or CLI implementation.

Core Retrieval Flow

1. Start with direct feature_refs when present. Open path-like refs directly.
2. Prefer filename/path lookup before broad text search when a Feature path, stem, or unambiguous ID exists.
3. When there is no direct Feature ref, check docs/features/INDEX.md if present; otherwise list docs/features/*.md filenames. Use task terms and touched paths to select at most 1-3 candidate Features before opening content.
4. If no clear candidate exists, record none found instead of reading every Feature.
5. Read the Feature page first when found; treat it as the delivery boundary and navigation entry.
6. Open linked ADR, Lesson, spec, plan, Evidence, research, discussion, bug report, PR, commit, and archive records only as needed.
7. Follow stale, superseded, deprecated, invalidated, or superseded_by pointers before relying on old material.
8. Summarize what was read: paths, document kinds, status, feature IDs, decisions, stale items, confidence, and open questions.

If retrieval discovers that a current Feature was missing, duplicated, or misleading in docs/features/INDEX.md, route the closeout to harness-knowledge-capture and run a local Feature Index check with knowledge_check.py --feature-index . Do not turn this into a global index audit unless the user explicitly asks for one.

Usage Recording

Only record documents that were used, not documents that were merely opened, skimmed, or considered as candidates.

After an Harness Feature, ADR, Lesson, Evidence, or AGENTS document materially changes the current scope, design choice, fix direction, verification gate, completion-claim judgment, or recurrence-prevention action, run:

python /using-harness/scripts/usage_record.py --root  --doc  --doc-type  --task "" --impact 

Use one of these impact values:

changed_scope
changed_design
changed_fix_direction
changed_verification_gate
supported_completion_claim
prevented_repeat_failure
shaped_change_narrative

Do not record Feature Index scans, candidate reads that did not affect the outcome, stale documents that were rejected, or files opened only to find a path.

Bug Retrieval Mode

For bug attribution, classify the result as:

existing Feature  | none found | ambiguous | stale/superseded

If a Feature is found, inspect ## Patch History, ## Patch Churn Review, related links, status, and Evidence.

If no Feature is found, say so explicitly. A negative retrieval result is useful evidence.

Retrieval itself must not update Patch History.

Reference Map

Use references only when their trigger applies.

• references/retrieval-order.md: read when search scope, source trust, stale document handling, or fallback search patterns are unclear.
• references/bug-retrieval-mode.md: read for non-tiny bugfix attribution, Feature ownership, Patch History, or ambiguous candidates.

Common Mistakes

| Mistake | Correction | | --- | --- | | Reading only the first search snippet. | Open the source path and inspect metadata/status. | | Treating search rank as authority. | Authority comes from document kind, status, lifecycle, and links. | | Stopping at a stale ADR or old plan. | Follow superseded_by, updates, or archive pointers to the current record. | | Assuming Feature owns every record. | Feature expresses delivery boundary; ADR expresses decision boundary; Lesson expresses failure-mode boundary. | | Debugging a non-tiny bug before attribution. | First establish whether it belongs to an existing Feature or prior fix chain, then debug with that context. |

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: solitudeTG
• Source: solitudeTG/harness-coding-skills
• License: MIT

Install and usage instructions live in the source repository linked above.