Harness Knowledge Mapper

Harness Knowledge Mapper

Auto-generate always-current knowledge maps from graph topology. Never stale because it's computed, not authored.

When to Use

• When AGENTS.md is outdated or doesn't exist — generate it from the graph
• After major refactoring — regenerate the knowledge map to reflect new structure
• On scheduled basis — keep documentation aligned with code
• When on_commit to main triggers fire
• NOT for validating existing AGENTS.md (use validate-context-engineering)
• NOT for fixing documentation drift (use align-documentation)

Prerequisites

A knowledge graph at .harness/graph/ enables full analysis. If no graph exists, the skill uses static analysis fallbacks (see Graph Availability section). Run harness scan to enable graph-enhanced analysis.

Graph Availability

Before starting, check if .harness/graph/graph.json exists.

If graph exists: Check staleness — compare .harness/graph/metadata.json scanTimestamp against git log -1 --format=%ct (latest commit timestamp). If graph is more than 10 commits behind (git log --oneline <scanTimestamp>..HEAD | wc -l), run harness scan to refresh before proceeding. (Staleness sensitivity: Medium)

If graph exists and is fresh (or refreshed): Use graph tools as primary strategy.

If no graph exists: Output "Running without graph (run harness scan to enable full analysis)" and use fallback strategies for all subsequent steps.

Pipeline Context (when orchestrated)

When invoked by harness-docs-pipeline, check for a pipeline field in .harness/handoff.json:

• If pipeline field exists: read DocPipelineContext from it
  • If pipeline.bootstrapped === true, this is a bootstrap invocation — generate full AGENTS.md without confirmation prompt
  • Write any generated documentation back as DocFix[] to pipeline.fillsApplied
  • This enables the orchestrator to track what was generated and verify it
• If pipeline field does not exist: behave exactly as today (standalone mode)

No changes to the skill's interface or output format — the pipeline field is purely additive.

Process

Phase 1: SURVEY — Query Graph for Structure

1. Module hierarchy: Query for module nodes and their contains edges to file nodes.

   query_graph(rootNodeIds=[all module nodes], includeTypes=["module", "file"], includeEdges=["contains"])
   

2. Entry points: Find file nodes with high out-degree but low in-degree (they initiate dependency chains).

   search_similar(query="main entry point index")
   

3. Layer structure: Query for layer nodes if defined.

4. Dependency flow: For each module, trace outbound imports edges to other modules.

   get_relationships(nodeId=<module>, direction="outbound", depth=1)
   

Fallback (without graph)

When no graph is available, use directory structure and file analysis:

1. Module hierarchy from directories: Use the directory structure as the module hierarchy — each directory represents a module. Glob for all source files to build the tree.
2. Entry points: Check package.json for main and exports fields. Glob for src/index.* and index.* patterns. These are the entry points.
3. Source file inventory: Glob for all source files (**/*.ts, **/*.tsx, **/*.js, **/*.jsx, etc.).
4. Documentation inventory: Glob for all doc files (**/*.md, docs/**/*).
5. Undocumented module detection: Diff the source directory set against the doc directory set. Source directories with no corresponding docs (no README.md, no matching doc file) are undocumented.
6. Existing knowledge map: Read existing AGENTS.md if present for current knowledge map state.
7. Dependency flow (approximate): Parse import statements in each module's files to determine which modules depend on which others.

Fallback completeness: ~50% — no semantic grouping; modules grouped by directory only; no cross-cutting concern detection.

Phase 2: GENERATE — Build Knowledge Map

Generate markdown sections following AGENTS.md conventions:

1. Repository Structure: Module hierarchy with brief descriptions derived from file contents and function names.

2. Key Entry Points: Files identified as entry points with their purpose (inferred from exports and naming).

3. Module Dependencies: For each module, list what it depends on and what depends on it. Format as a dependency table.

4. API Surface: Public exports from each module, grouped by type (functions, classes, types).

5. Patterns and Conventions: Detected patterns from graph structure (e.g., "all services follow Repository pattern", "tests co-located with source").

Phase 3: AUDIT — Identify Coverage Gaps

1. Undocumented modules: Use check_docs to find code nodes without documents edges.

2. Missing descriptions: Modules with no README or doc file.

3. Stale references: If an existing AGENTS.md exists, compare its file references against the graph to find mentions of files that no longer exist.

Phase 4: OUTPUT — Write Knowledge Map

1. Default: Write to AGENTS.md in project root.
2. Custom path: Write to specified output path.
3. Diff mode: If AGENTS.md exists, show what changed rather than overwriting.

Output

## Generated Knowledge Map

### Repository Structure
- **packages/core/** — Core library: context assembly, entropy detection, constraints, feedback
  - src/context/ — Token budget, filtering, doc coverage, knowledge map validation
  - src/entropy/ — Drift detection, dead code analysis, pattern violations
  - src/constraints/ — Layer validation, circular dependency detection, boundaries
  - src/feedback/ — Self-review, peer review, diff analysis

- **packages/graph/** — Knowledge graph: store, query, ingest, search
  - src/store/ — LokiJS-backed graph store, vector store, serialization
  - src/query/ — ContextQL traversal, projection
  - src/ingest/ — Code, git, knowledge, connector ingestion
  - src/search/ — FusionLayer hybrid search

### Entry Points
1. packages/core/src/index.ts — Core library barrel export
2. packages/graph/src/index.ts — Graph library barrel export
3. packages/cli/src/index.ts — CLI entry point (Commander.js)
4. packages/mcp-server/src/server.ts — MCP server registration

### Coverage Gaps
- 3 modules have no documentation
- 5 files have no test coverage

Graph Refresh

After generating documentation, refresh the graph so new documents edges reflect the updated docs:

harness scan [path]

This ensures subsequent graph queries (impact analysis, drift detection) include the newly generated documentation.

Harness Integration

• harness scan — Recommended before this skill for full graph-enhanced analysis. If graph is missing, skill uses directory structure fallbacks.
• harness validate — Run after acting on findings to verify project health.
• Graph tools — This skill uses query_graph, get_relationships, and check_docs MCP tools.

Success Criteria

• Knowledge map generated with all sections (structure, entry points, dependencies, API surface, patterns)
• Coverage gaps identified (undocumented modules, missing descriptions, stale references)
• Output written to AGENTS.md (or specified path) in proper markdown format
• Report follows the structured output format
• All findings are backed by graph query evidence (with graph) or directory/file analysis (without graph)

Rationalizations to Reject

Rationalization	Why It Is Wrong
"The graph is a few commits behind, but it is close enough for knowledge mapping"	If the graph is more than 10 commits behind, run harness scan before proceeding. A stale graph produces a knowledge map with missing modules.
"No graph exists, so this skill cannot produce useful output"	The fallback strategy is explicit: use directory structure and file analysis. Fallback completeness is ~50%, significantly better than nothing.
"The existing AGENTS.md is outdated, so I will overwrite it with the generated version"	Never overwrite without confirmation. Existing AGENTS.md may contain carefully authored context the graph cannot infer.
"The module descriptions I inferred from function names are accurate enough"	Inferred descriptions are starting points. Phase 3 (AUDIT) exists to identify coverage gaps. Name-based inference misses purpose, constraints, and relationships.

Examples

Example: Generating AGENTS.md from Graph

Input: No AGENTS.md exists, graph is current after harness scan

1. SURVEY   — query_graph for module hierarchy: 4 packages found
              search_similar for entry points: 4 identified
              get_relationships for dependency flow per module
2. GENERATE — Built 5 sections: structure, entry points,
              dependencies, API surface, patterns
3. AUDIT    — check_docs found 3 undocumented modules,
              5 files with no test coverage
4. OUTPUT   — Wrote AGENTS.md to project root (new file)

Output:
  AGENTS.md generated (142 lines)
  Coverage gaps: 3 undocumented modules, 5 untested files
  No stale references (fresh generation)

Gates

• Graph preferred, fallback available. If no graph exists, use directory structure and file analysis to build the knowledge map. Do not stop — produce the best map possible.
• Never overwrite without confirmation. If AGENTS.md exists, show the diff and ask before replacing.

Escalation

• When >50% of modules are undocumented: Flag as critical documentation debt.
• When graph structure doesn't match directory structure: The graph may be stale — recommend re-scanning.