Analyze — Document Landscape Analysis & Knowledge Mapping

Map, understand, and evaluate a collection of documents as a body of knowledge. Identify structure, themes, gaps, redundancies, conflicts, and staleness. Produce an actionable analysis with reorganization recommendations.

Core Principles

1. Landscape-first: Build the map before judging — understand what exists before critiquing
2. Theme-driven: Group documents by what they're about, not just where they live
3. Conflict detection: Find contradictions between documents that may confuse readers
4. Staleness awareness: Identify documents that may be outdated based on content signals
5. Non-destructive: Only reads and reports — never modifies source documents
6. Reorganization as suggestion: Propose better structures, don't impose them

When to Use Analyze vs. Audit

Workflow

Step 1: Determine Scope

Parse the arguments to determine what to analyze:

1. If a path argument is provided (e.g., /spec-forge:analyze ../../aipartnerup-docs), use that as the root
2. If no path, use the current working directory's docs/ directory
3. If multiple paths are provided, analyze all of them as one collection

Use AskUserQuestion to understand the user's goals:

• What is this collection? (e.g., "ecosystem docs for multiple products", "research notes", "mixed specs and decisions")
• What do you want to understand? Options:
  • Full landscape analysis (recommended for first time)
  • Find conflicts and contradictions
  • Find gaps and missing coverage
  • Suggest reorganization
  • All of the above

Step 2: Document Discovery & Inventory

Scan all documents in the target path(s):

Fast path (preferred): resolve <sf_scripts> (see @../shared/scripts.md) and run python3 "<sf_scripts>/sf-scan.py" --root "<root>" --docs-only to enumerate every markdown document with its path, word count, and any declared requirement IDs in one pass. Use that inventory as the deterministic starting point. Fallback: if python3 is unavailable or the script is not found, glob for all markdown files recursively by hand. Either way, sf-scan is only a facts collector on an arbitrary doc collection — the model still judges each document's TYPE (below), its themes, and its conflicts. Switch to the manual fallback silently.

1. Enumerate all markdown files recursively — path, per-file word count, and declared IDs come from the sf-scan inventory above (glob by hand only in the fallback)
2. Read enough of each document to extract its metadata and claims; for large files read strategically (headings + relevant sections) rather than a fixed prefix
3. Extract metadata for each document:
   • File path and directory position
   • Title (first H1 or filename)
   • Approximate word count
   • Last modified date (git log if available, file stat otherwise)
   • Document type classification (see below)
   • Key entities mentioned (product names, system names, technologies)
   • Key claims or decisions stated
   • Internal links to other documents
   • Apparent audience (developers, product, leadership, external)

Document type classification:

Display the inventory:

Document Collection: {name}
  Root: {path}
  Total documents: {N}
  Total words: ~{N}k

  Directory Structure:
    {dir}/           ({n} docs) — {apparent purpose}
    {dir}/{subdir}/  ({n} docs) — {apparent purpose}
    ...

  By Type:
    vision:       {n} docs
    architecture: {n} docs
    research:     {n} docs
    ...

Step 3: Theme & Cluster Analysis

Group documents by what they're actually about, regardless of directory structure:

3.1 Identify Themes

Read through all documents and identify the major themes/topics that emerge:

• Product/system names mentioned across multiple docs
• Recurring concepts or concerns
• Shared vocabulary or domain terms

3.2 Build Theme Clusters

For each theme, list which documents contribute to it:

Theme Clusters:

  "{Theme A}" — {description}
    Primary:    {docs that are mainly about this}
    Secondary:  {docs that touch on this}
    Coverage:   {Good / Partial / Sparse}

  "{Theme B}" — {description}
    Primary:    ...
    Secondary:  ...
    Coverage:   ...

3.3 Cross-Reference Map

Build a document relationship map. Pull the deterministic input first: run python3 "<sf_scripts>/sf-trace.py" ids <file...> to extract the requirement IDs each document declares, and use those exact IDs as the input to the reference map rather than eyeballed mentions. Then apply judgement:

• Which docs reference each other?
• Which docs should reference each other but don't?
• Are there isolated documents with no connections?

Generate a Mermaid graph showing document relationships. (Fall back to reading the declared IDs by hand if the script is unavailable; conflict and theme judgement always stays with the model.)

Step 4: Conflict & Contradiction Detection

Systematically compare documents for conflicts:

4.1 Factual Conflicts

Look for places where two documents state contradictory facts:

• Different architecture descriptions for the same system
• Conflicting technology choices or version numbers
• Contradictory timelines or priorities
• Inconsistent naming (same thing called different names, or same name for different things)

For each conflict:

CONFLICT-{NNN}: {title}
  Doc A: {path} — states "{claim A}" (section: {section})
  Doc B: {path} — states "{claim B}" (section: {section})
  Nature: {factual contradiction / naming inconsistency / version mismatch / priority conflict}
  Impact: {who gets confused and how}
  Resolution suggestion: {which doc is likely correct, or how to reconcile}

4.2 Strategic Conflicts

Look for higher-level misalignments:

• Vision docs that contradict architecture decisions
• Research findings that aren't reflected in decisions
• Ideas that overlap with or contradict existing plans
• Decisions that seem to ignore relevant research

4.3 Temporal Conflicts

Look for staleness-related contradictions:

• Old docs describing plans that newer docs have superseded
• Documents referencing deprecated technologies or abandoned features
• Timelines or milestones that have clearly passed without update

Step 5: Gap Analysis

Identify what's missing from the document collection:

5.1 Coverage Gaps

Based on the themes and types identified:

• Are there themes with no vision/strategy doc?
• Are there systems with no architecture doc?
• Are there decisions with no supporting research?
• Are there ideas that were never evaluated or decided on?
• Is there a getting-started guide for new team members?

5.2 Depth Gaps

Some areas may be documented but not deeply enough:

• Vision without concrete roadmap
• Architecture without component details
• Research without conclusions or recommendations
• Decisions without recorded rationale

5.3 Audience Gaps

Check if all relevant audiences are served:

• Developer documentation (architecture, API, guides)
• Product documentation (vision, requirements, roadmap)
• Leadership documentation (strategy, metrics, status)
• External documentation (README, getting started, examples)

Step 6: Redundancy Detection

Find documents that overlap significantly:

1. Near-duplicates: Documents covering the same topic with slightly different content
2. Superseded docs: Older versions that should have been replaced but weren't
3. Scattered coverage: Same topic spread across multiple docs that could be consolidated

For each redundancy:

REDUNDANCY-{NNN}: {title}
  Documents: {list of overlapping docs}
  Overlap: {what they share}
  Recommendation: {merge into X / archive Y / consolidate into new doc Z}

Step 7: Staleness Assessment

Evaluate document freshness:

1. Age signals: Last modified date, referenced dates in content
2. Content signals: Mentions of deprecated technologies, past tense for future plans, "TODO" items that should have been resolved
3. Context signals: Referenced systems that no longer exist, links that would be broken

Classify each document:

• Current: Content appears up-to-date
• Possibly stale: Some signals of age but content may still be valid
• Likely stale: Strong signals that content is outdated
• Archival: Document is historical record, not meant to be current

Step 8: Generate Analysis Report

Write the analysis report to {target-root}/analysis-report.md (or user-specified path).

Report format:

# Document Landscape Analysis

> Collection: {name}
> Root: {path}
> Analyzed: {date}
> Documents: {N} ({total words}k words)

## Executive Summary

{3-4 paragraphs: what this collection is about, its strengths as a knowledge base,
the most important issues found, and the top recommended actions}

## Document Map

### By Directory

| Directory | Docs | Purpose | Health |
|-----------|------|---------|--------|
| {dir}     | {n}  | {purpose} | {Good/Mixed/Poor} |

### By Type

| Type | Count | Key Documents |
|------|-------|---------------|
| vision | {n} | {most important ones} |
| architecture | {n} | ... |
| ... | ... | ... |

### Relationship Graph

~~~mermaid
graph LR
  ...
~~~

## Theme Analysis

### {Theme 1}: {name}

**Coverage**: {Good / Partial / Sparse}
**Key documents**: {list}
**Gaps**: {what's missing}

### {Theme 2}: {name}
...

## Findings

### Conflicts ({n} found)

{Ordered by severity}

#### CONFLICT-001: {title}
...

### Gaps ({n} found)

#### GAP-001: {title}
- **Area**: {theme/topic}
- **What's missing**: {description}
- **Why it matters**: {impact}
- **Recommendation**: {what to create or expand}

### Redundancies ({n} found)

#### REDUNDANCY-001: {title}
...

### Staleness ({n} documents flagged)

| Document | Status | Signals | Recommendation |
|----------|--------|---------|----------------|
| {path}   | Likely stale | {signals} | {update/archive/delete} |

## Reorganization Recommendations

{If the current structure has significant issues, propose an alternative organization.
Show current structure → proposed structure side by side.
Only propose reorganization if it would meaningfully improve navigability — don't reorganize for aesthetics.}

### Current Structure
~~~
{current directory tree}
~~~

### Proposed Structure
~~~
{proposed directory tree with annotations}
~~~

### Migration Steps
1. {step — which files to move/merge/archive}
2. ...

## Priority Actions

| # | Action | Addresses | Effort | Impact |
|---|--------|-----------|--------|--------|
| 1 | {action} | CONFLICT-001, GAP-003 | {S/M/L} | {High/Med/Low} |
| 2 | {action} | REDUNDANCY-001 | {S/M/L} | {High/Med/Low} |
| ... | ... | ... | ... | ... |

Step 9: Present Results

Display a summary to the user:

Analysis complete: {collection-name}

  Documents analyzed: {N}
  Themes identified: {N}
  Conflicts: {n}
  Gaps: {n}
  Redundancies: {n}
  Stale documents: {n}

  Report: {path-to-analysis-report.md}

  Top 3 priority actions:
    1. {action} — {impact}
    2. {action} — {impact}
    3. {action} — {impact}

Use AskUserQuestion to ask what to do next:

• Deep dive: Explore a specific theme or conflict in detail
• Fix conflicts: Help resolve specific contradictions
• Fill gaps: Generate missing documents using spec-forge skills
• Reorganize: Execute the proposed reorganization (move/rename/merge files)
• Done: Just the report for now

Step 10: Follow-Up Actions (Optional)

Based on user choice:

Deep dive: Read the relevant documents in full, provide a detailed analysis of the specific area, and discuss with the user.

Fix conflicts: For each conflict, read both documents in full, determine the correct information (asking the user when uncertain), and propose specific edits. Only apply edits after user approval.

Fill gaps: For identified gaps, suggest which spec-forge skill to use:

• Missing architecture doc → /spec-forge:tech-design
• Missing requirements → /spec-forge:prd or /spec-forge:srs
• Missing test cases → /spec-forge:test-cases
• Missing strategy/research → manual writing or /spec-forge:idea for exploration

Reorganize: Execute file moves/renames step by step, confirming with user before each destructive action (deletes, merges). Update internal links after moves.

Notes

1. Cross-repo support: Can analyze documents across multiple repositories by providing multiple paths
2. No code requirement: Unlike /audit, /analyze works purely on documents — no codebase needed
3. Preserves originals: Never modifies source documents during analysis (only during explicit follow-up actions)
4. Incremental: If a previous analysis-report.md exists, note what changed since last analysis
5. Language agnostic: Works with any documentation regardless of the project's programming language
6. Scale aware: For very large collections (50+ docs), focus depth on the most important documents and provide breadth coverage for the rest