tercel/spec-forge/analyze

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