Knowledge Discovery

---
name: knowledge-discovery
description: >
  Discovers and inventories every pre-existing project knowledge source in a
  repository - AGENTS.md, CLAUDE.md, .cursor/rules/, .cursorrules,
  .windsurfrules, .github/copilot-instructions.md, .claude/, skills/,
  agents/, README.md, CONTRIBUTING.md, docs/, ADRs, lessons-learned files,
  generated AI documentation, and prior Project Memory output. Extracts
  atomic claims, tags provenance, detects overlaps and contradictions.
  Produces the Existing Knowledge Inventory for downstream verification.
  Read-only; never verifies, classifies, or edits.
---

# Knowledge Discovery

Answer one question before any other Project Memory work:

> What does this repository already believe about itself, and where did each
> belief come from?

# Core Principle

Existing knowledge is scattered across tools never designed to agree -
different authors (human or AI), different times, never reconciled. Treat it
like five engineers' personal notes on the same system: individually useful,
collectively unreliable until cross-checked.

Output is NOT the truth about the project. It is:

```text
Everything the repository currently claims about itself,
where each claim came from,
where claims overlap,
where claims disagree.
```

Inventory = candidate claims, NOT approved memory. Verification,
classification, and reconstruction happen downstream:

* verify - `repository-audit` / `codebase-memory`
* classify - `knowledge-classification` / `obsolete-knowledge`
* design target architecture - `memory-architecture`
* edit - `memory-edit`

# Mandatory First Step

Run this Skill FIRST in any full Project Memory audit, initial memory build,
or explicit reconstruction - whenever pre-existing knowledge sources exist.
Everything downstream consumes the inventory; skipping it means classifying
and editing unverified scattered beliefs blind.

# Read-Only Boundary

This Skill inventories only. It never:

* verifies claims against source code, tests, configuration, build/CI, or
  Git history
* decides Current / Historical / Deprecated / Superseded / Obsolete status
* resolves contradictions - surface only
* modifies, moves, merges, or deletes any file
* assumes a source is authoritative or unreliable because of its origin tool
* invents claims not present in a source

# Known Existing-Knowledge Locations

Scan for all that are present. Absence is not an error; report only what
exists.

## Universal / Cross-Tool

```text
AGENTS.md
README.md
CONTRIBUTING.md
CHANGELOG.md
CODEOWNERS
CONCEPTS.md (project glossary / shared vocabulary file)
docs/
docs/adr/
docs/decisions/
docs/architecture/
docs/lessons/ or docs/lessons-learned/
docs/history/
docs/runbooks/
.github/ISSUE_TEMPLATE/
.github/PULL_REQUEST_TEMPLATE.md
```

## AI-Agent / AI-IDE Conventions

```text
CLAUDE.md
.claude/
  .claude/commands/
  .claude/skills/
  .claude/agents/
  .claude/settings.json / settings.local.json
.cursor/
  .cursor/rules/
.cursorrules
.windsurfrules
.github/copilot-instructions.md
.github/copilot/
.aider.conf.yml / .aider/
opencode config / agent definitions (repository-specific location)
Any other *rules*, *instructions*, or *.agent.md file recognizable as
Agent/IDE configuration
```

## Repository-Specific Agent Tooling

```text
agents/
skills/
Any directory containing SKILL.md, AGENT.md, or equivalent frontmatter-based
definitions
```

## Prior Memory / Generated Output

```text
MEMORY.md (agent auto-memory store, when present)
Any docs/ subtree already following a Project-Memory-like structure
(architecture/, decisions/, solutions/, lessons/, constraints/, workflows/,
reference/, history/) - may be prior Project Memory output or another tool's
independent attempt. Do not assume either.
Any file clearly AI-generated ("Generated by" headers, boilerplate
structure, session-summary style).
```

List is not exhaustive. Unrecognized conventions that tell an Agent or
contributor something about the project (e.g. project-specific `.knowledge/`)
belong in the scan.

# Workflow

## Step 1 - Enumerate

List every existing-knowledge location. Record path, apparent
tool/convention, rough size (files/lines). Do not read full contents yet if
the repository is large - build the map first.

## Step 2 - Read and Extract

Read each source; extract atomic claims.

## Step 3 - Tag Provenance

Record the six provenance fields per claim (below).

## Step 4 - Cluster by Concept

Group claims describing the same subject across sources - cluster by the
future question the claim answers, not by exact wording (same discipline as
`knowledge-classification` semantic duplicate detection).

## Step 5 - Flag Cluster Status

Mark each cluster: Consistent / Redundant / Conflicting / Partial /
Complementary.

## Step 6 - Flag Durability

Mark each claim or cluster: Likely Durable / Likely Session-Local / Unknown.
Signal for `knowledge-classification`, not a verdict.

## Step 7 - Produce the Inventory

Return the Existing Knowledge Inventory (format below) to the parent
`project-memory` Agent. Do not proceed to classification, verification, or
editing.

# Extraction Rules

An atomic claim is a single, independently checkable statement:

```text
"The project uses pnpm as its package manager."
"We rejected Redis because of licensing constraints in production."
```

Do NOT extract:

* formatting instructions with no project-knowledge content
  (e.g. "always answer in markdown")
* tool-invocation syntax with no durable project fact
  (e.g. "call this function like this")
* boilerplate template text with no repository-specific content

These are legitimate `AGENTS.md`/`CLAUDE.md` content but not project
knowledge - out of scope for this inventory.

# Provenance Fields

Per claim, record:

```text
Claim
Origin Path
Origin Tool/Convention
Apparent Authorship: Human | AI Agent | AI IDE | Unknown
Apparent Age Signal: <git blame date / "no signal available">
Section/Heading (if applicable)
```

No signal -> `Unknown`. Never guess authorship or age from writing style;
require Git history, explicit header, or commit metadata.

# Clustering

Cluster = claims answering the same future question across sources:

```text
Subject: Package manager
Claim A - AGENTS.md: "Use pnpm for all installs."
Claim B - CLAUDE.md: "Run npm install to set up dependencies."
Claim C - .cursor/rules/setup.md: "yarn install && yarn build"
```

One cluster, three conflicting claims - not three pieces of knowledge.

## Cluster Statuses

```text
Consistent - all sources agree; still needs evidence verification, no
  cross-source conflict.
Redundant - multiple sources say the same thing in different words;
  consolidation candidate.
Conflicting - claims cannot all be true simultaneously.
Partial / Complementary - different facets of the same subject, no
  contradiction (e.g. one describes what, another why).
```

Never resolve `Conflicting` clusters - surface clearly. Resolution requires
repository evidence (`repository-audit`/`codebase-memory`) plus a
classification decision.

## Durability Signals

```text
Likely Durable - architecture, constraints, decisions, reusable
  engineering knowledge.
Likely Session-Local / Scratch - task-specific note, temporary TODO,
  in-progress thought, debugging narration never cleaned up.
Unknown
```

# Inventory Output Format

```markdown
## Existing Knowledge Inventory

### Sources Found

| Path | Tool/Convention | Size | Apparent Authorship |
|---|---|---|---|
| `<path>` | `<convention>` | `<size>` | `<authorship>` |

### Claims

#### Cluster: <subject>

- **Status:** Consistent | Redundant | Conflicting | Partial / Complementary
- **Durability Signal:** Likely Durable | Likely Session-Local | Unknown

| Claim | Origin Path | Origin Tool | Authorship | Age Signal |
|---|---|---|---|---|
| `<claim>` | `<path>` | `<tool>` | `<authorship>` | `<signal>` |

(repeat per cluster)

### Conflicting Clusters (Requires Verification + Classification)

- **Subject:** `<subject>`
  - `<claim A>` (`<origin A>`) vs `<claim B>` (`<origin B>`)
  - Why they conflict:
  - Cannot be resolved here - requires repository evidence.

### Redundant Clusters (Consolidation Candidates)

- **Subject:** `<subject>`
  - Origins: `<paths>`
  - Apparent duplication, not contradiction.

### Likely Session-Local / Scratch Content

- `<path>` - `<why it looks non-durable>`

### Dual/Competing Entry Points

- `<path A>` and `<path B>` both appear to function as a primary
  Agent-facing entry point. Flag for `memory-architecture` reconciliation.

### Coverage

- Locations checked:
- Locations not present:
- Locations skipped, and why:

### Limitations

- <limitation>

### L0 Domain Summaries (when AGENTS.md l0_domains present)

| Domain | L0 Summary |
|--------|-----------|
| <domain> | <one-line summary> |

These summaries are used by `memory-architecture` to populate the `l0_domains`
frontmatter in AGENTS.md for Level 0 progressive loading.

### Handoff

- To `repository-audit` / `codebase-memory`: claims requiring evidence
  verification.
- To `knowledge-classification`: clusters requiring type/state
  classification.
- To `memory-architecture`: dual entry points and structural overlaps
  requiring a reconciliation plan.
```

## Compact Table Mode

For a repository with many small sources, prefer one table over a
subsection per claim:

| Subject | Sources | Status | Durability |
|---|---|---|---|
| Package manager | AGENTS.md, CLAUDE.md, .cursor/rules/setup.md | Conflicting | Likely Durable |
| Auth token storage | docs/architecture/auth.md | Consistent | Likely Durable |
| "Fixed the flaky test on 8/12" note | CLAUDE.md | N/A | Likely Session-Local |

Expand only clusters needing explanation (conflicting, or high apparent
value).

# Handoff

Return the inventory to the parent `project-memory` Agent. Parent routes:

```text
Conflicting / Redundant / Consistent clusters
        ↓
repository-audit + codebase-memory (verify against reality)
        ↓
knowledge-classification (assign type/state per cluster)
        ↓
obsolete-knowledge (for anything contradicted or superseded)
        ↓
memory-architecture (design canonical structure + consolidation mapping)
        ↓
memory-edit (execute)
        ↓
memory-verification (confirm)
```

Do not perform any of these steps yourself.

# Hard Rules

* Do not verify claims against repository evidence - belongs to
  `repository-audit` / `codebase-memory`.
* Do not classify knowledge type or state - belongs to
  `knowledge-classification`.
* Do not resolve conflicts - surface them.
* Do not modify, move, merge, or delete any file.
* Do not assume correctness or incorrectness from a source's origin tool, or
  durability from formatting polish.
* Do not invent claims not present in the source text.
* Do not guess authorship or age without a signal; use `Unknown`.
* Do not treat this Skill's output as approved memory - unverified
  inventory; unreadable locations (too large, binary, inaccessible) become
  limitations, never silent omissions.

# Completion Criteria

Discovery is complete when:

```text
Known locations enumerated, present sources read
Atomic claims extracted, provenance tagged per claim
Claims clustered by subject, status + durability assigned
Dual/competing entry points flagged
Coverage, limitations (incl. unreadable locations) recorded
L0 domain summaries extracted from AGENTS.md l0_domains frontmatter (when present)
No repository files modified; inventory returned to parent Agent
```