context-analyzer

Purpose

Scan project structure and build a context model for intelligent documentation creation.

Problem Solved: AI assistants lack awareness of project context, existing artifacts, and current workflow state when creating documentation, leading to missing references and duplicate content.

Solution: Analyze project directories, parse artifact metadata and traceability sections, and build a context model that surfaces relevant information for new document creation.

When to Use This Skill

Use context-analyzer when:

• Starting documentation work in an existing project

• Creating a new artifact that needs upstream references

• Need to understand what documentation already exists

• Want to identify gaps in documentation coverage

• Preparing context for doc-* skill invocation

Do NOT use when:

• Project has no existing documentation

• Working on a single, isolated document

• Full project audit needed (use trace-check instead)

Skill Inputs

Input Type Required Description

project_root string Yes Root path of the project to analyze

target_artifact_type string No Artifact type being created (e.g., "PRD", "SPEC")

depth string No Analysis depth: "quick" (structure only), "standard" (default), "deep" (full content)

Skill Workflow

Step 1: Scan Project Structure

Enumerate all documentation artifacts by type and location:

Directory Patterns:

{project_root}/ ├── docs/ │ ├── BRD/ │ ├── PRD/ │ ├── EARS/ │ ├── BDD/ │ ├── ADR/ │ ├── SYS/ │ ├── REQ/ │ ├── IMPL/ │ ├── CTR/ │ ├── SPEC/ │ └── TASKS/ └── ai_dev_flow/ (framework templates)

Artifact Discovery:

Example discovery pattern

find {project_root}/docs -name ".md" -o -name ".yaml" -o -name "*.feature"

Output Structure:

artifact_inventory: BRD: count: 3 files: - id: BRD-01 path: docs/BRD/BRD-01_platform_foundation.md title: Platform Foundation status: Approved - id: BRD-02 path: docs/BRD/BRD-02_partner_integration.md title: Partner Integration status: Draft PRD: count: 2 files: - id: PRD-01 path: docs/PRD/PRD-01_core_features.md title: Core Features status: In Review SPEC: count: 0 files: []

Step 2: Parse Artifact Metadata

Extract metadata and key information from discovered artifacts:

YAML Frontmatter Extraction:

From document header

title: "BRD-01: Platform Foundation" tags:

• platform-brd
• shared-architecture custom_fields: layer: 1 artifact_type: BRD status: Approved

Document Control Extraction:

Document Control

Parsed Metadata Model:

artifact_metadata: BRD-01: title: Platform Foundation layer: 1 status: Approved version: 2.1.0 last_updated: 2025-11-15 tags: [platform-brd, shared-architecture]

Step 3: Extract Traceability Information

Parse Section 7 Traceability from each artifact:

Upstream Sources Extraction:

Upstream Sources

Downstream Artifacts Extraction:

Downstream Artifacts

Traceability Graph:

traceability_graph: BRD-01: upstream: [] downstream: [PRD-01, PRD-00] PRD-01: upstream: [BRD-01] downstream: [EARS-01, SPEC-01] SPEC-01: upstream: [PRD-01, REQ-01] downstream: [TASKS-01]

Step 4: Determine Workflow Position

Calculate current position in SDD workflow:

Layer Mapping:

Layer Artifact Type Required Upstream

1 BRD None

2 PRD BRD

3 EARS PRD

4 BDD EARS

5 ADR BDD

6 SYS ADR

7 REQ SYS

8 IMPL REQ (optional)

9 CTR IMPL or REQ (optional)

10 SPEC REQ, optional IMPL/CTR

11 TASKS SPEC

Position Analysis:

workflow_position: completed_layers: [1, 2, 3] current_layer: 4 next_required: [BDD, ADR] gaps: - layer: 3 type: EARS status: incomplete reason: "Only 2 of 5 PRD features have EARS coverage"

Step 5: Identify Upstream Candidates

For a target artifact type, identify relevant upstream documents:

Relevance Scoring:

Factor Weight Description

Direct upstream 50% Immediate predecessor in workflow

Topic match 30% Key terms and domain alignment

Recency 10% Recently updated documents

Status 10% Approved documents preferred

Upstream Candidates Output:

upstream_candidates: target_type: SPEC candidates: - id: REQ-01 relevance: 95% title: API Requirements reason: "Direct upstream, topic match: API, approved status" - id: REQ-02 relevance: 80% title: Data Model Requirements reason: "Direct upstream, related topic: data" - id: ADR-005 relevance: 70% title: API Architecture Decision reason: "Architecture context for API design"

Step 6: Extract Key Terms

Build project vocabulary from existing documentation:

Term Extraction Methods:

• Document titles and headers

• Glossary sections

• Frequently used technical terms

• Domain-specific vocabulary

Key Terms Output:

key_terms: domain_terms: - term: workflow frequency: 45 documents: [BRD-01, PRD-01, REQ-01] - term: resource frequency: 32 documents: [BRD-01, REQ-02, SPEC-01] technical_terms: - term: WebSocket frequency: 18 documents: [ADR-003, SPEC-01] - term: PostgreSQL frequency: 12 documents: [BRD-01, ADR-000]

Step 7: Build Context Model

Assemble complete context model for session use:

Complete Context Model:

context_model: project_root: /path/to/project scan_timestamp: 2025-11-29T14:30:00Z scan_depth: standard

artifact_inventory: total_count: 25 by_type: BRD: 3 PRD: 5 EARS: 4 BDD: 6 ADR: 3 REQ: 4 SPEC: 0 TASKS: 0

workflow_position: completed_layers: [1, 2, 3, 4, 5, 7] current_layer: 7 ready_for: [SPEC, TASKS] gaps: - type: SYS status: missing impact: "SPEC creation may lack system context"

upstream_candidates: target_type: SPEC primary: - id: REQ-01 title: Core API Requirements relevance: 95% secondary: - id: ADR-003 title: WebSocket Architecture relevance: 75%

key_terms: domain: [workflow, resource, validation, processing] technical: [WebSocket, PostgreSQL, Redis, REST API]

coverage_gaps: - area: Testing description: "BDD scenarios cover only 60% of EARS requirements" - area: Implementation description: "No SPEC or TASKS documents created yet"

Example Usage

Example 1: Pre-SPEC Context

User Request: "I'm about to create a SPEC document, what context do I have?"

Context Analysis:

context_summary: target: SPEC creation readiness: ready upstream_available: - REQ-01: Core API Requirements (Approved) - REQ-02: Data Model Requirements (Approved) - ADR-003: WebSocket Architecture (Approved) recommended_references: - "Reference REQ-01 for API endpoint specifications" - "Include ADR-003 for WebSocket implementation decisions" warnings: - "No CTR (contract) documents exist - consider if API contracts needed"

Example 2: Gap Analysis

User Request: "What documentation is missing in this project?"

Gap Analysis Output:

documentation_gaps: critical: - type: SYS reason: "No system requirements linking ADR to REQ" impact: "REQ documents may lack architectural context" - type: SPEC reason: "No technical specifications for implementation" impact: "Cannot proceed to code generation" moderate: - type: BDD coverage: 60% reason: "4 of 10 EARS requirements have BDD scenarios" low: - type: IMPL reason: "Implementation plan optional but recommended for complex projects"

Example 3: Quick Structure Check

User Request: "What docs exist in this project?"

Quick Scan Output (depth: quick):

project_structure: docs_directory: /project/docs artifact_counts: BRD: 3 PRD: 5 EARS: 4 BDD: 6 ADR: 3 SYS: 0 REQ: 4 IMPL: 0 CTR: 0 SPEC: 0 TASKS: 0 total_artifacts: 25 workflow_coverage: 50% (6 of 12 layers)

Integration with Other Skills

Integration Description

skill-recommender Provides project context for better recommendations

doc-* skills Supplies upstream candidates and key terms

quality-advisor Shares artifact inventory for validation

workflow-optimizer Provides workflow position data

trace-check Overlaps with traceability extraction (uses trace-check for deep validation)

Quality Gates

Definition of Done

• Project structure scanned successfully

• All artifact types discovered

• Metadata extracted from discovered artifacts

• Traceability graph built

• Workflow position calculated

• Upstream candidates identified for target type

• Context model assembled and returned

Performance Targets

Metric Target

Quick scan latency <500ms

Standard scan latency <2s for 100 artifacts

Deep scan latency <5s for 100 artifacts

Memory usage <200MB for 100 artifacts

Traceability

Required Tags:

@prd: PRD.000.002 @adr: ADR-000

Upstream Sources

Source Type Reference

PRD-00 Product Requirements PRD-00

ADR-000 Architecture Decision ADR-000

Downstream Artifacts

Artifact Type Reference

skill-recommender Skill Consumer Uses context for better recommendations

doc-* skills Skill Consumer Uses context for artifact creation

Version Information

Version: 1.0.0 Created: 2025-11-29 Status: Active Author: AI Dev Flow Framework Team