detect-pack

detect-pack

Consolidate all detect outputs into a scored index with risk heatmap and unknowns backlog.

Context Files

• $JAAN_LEARN_DIR/jaan-to-detect-pack.learn.md - Past lessons (loaded in Pre-Execution)
• $JAAN_TEMPLATES_DIR/jaan-to-detect-pack.template.md - Output template
• ${CLAUDE_PLUGIN_ROOT}/docs/extending/language-protocol.md - Language resolution protocol
• ${CLAUDE_PLUGIN_ROOT}/docs/extending/detect-pack-reference.md - Evidence formats, consolidation logic, output templates
• ${CLAUDE_PLUGIN_ROOT}/docs/extending/detect-shared-reference.md - Shared standards: Evidence Format, Confidence Levels, Codebase Content Safety

Output path: $JAAN_OUTPUTS_DIR/detect/ — flat files, overwritten each run (no IDs).

Important: This skill does NOT scan the repository directly. It reads and consolidates outputs from the 5 detect skills.

Input

Arguments: $ARGUMENTS — parsed in Step 0.0. Repository path and mode determined there.

---

Pre-Execution Protocol

MANDATORY — Read and execute ALL steps in: ${CLAUDE_PLUGIN_ROOT}/docs/extending/pre-execution-protocol.md Skill name: detect-pack Execute: Step 0 (Init Guard) → A (Load Lessons) → B (Resolve Template) → C (Offer Template Seeding)

Language Settings

Read and apply language protocol: ${CLAUDE_PLUGIN_ROOT}/docs/extending/language-protocol.md Override field for this skill: language_detect-pack

---

PHASE 1: Consolidation (Read-Only)

Step 0.0: Parse Arguments

Arguments: $ARGUMENTS

Argument	Effect
(none)	Light mode (default): Heatmap + domain scores, single summary file
[repo]	Read detect outputs from specified repo (applies to both modes)
--full	Full mode: Full consolidation with evidence index and unknowns backlog (current behavior)

Mode determination:

• If $ARGUMENTS contains --full as a standalone token → set run_depth = "full"
• Otherwise → set run_depth = "light"

Strip --full token from arguments. Set repo_path to remaining arguments (or current working directory if empty).

Thinking Mode

If run_depth == "full": ultrathink If run_depth == "light": megathink

Use extended reasoning for:

• Cross-domain pattern recognition
• Risk correlation across domains
• Evidence ID validation and deduplication
• Overall score calculation

Step 0: Check Detect Outputs & Detect Platforms

Check for Detect Outputs

Glob $JAAN_OUTPUTS_DIR/detect/{dev,design,writing,product,ux}/ to see which detect skills have run.

If NO detect outputs exist:

Display:

"No detect outputs found. Is this a multi-platform project? [y/n]"

If YES: Ask: "Enter platform names (comma-separated, e.g., web,backend,mobile): " Display orchestration guide:

"To analyze all platforms, run detect skills for each:

Platform: {platform1} 1. /jaan-to:detect-dev 2. /jaan-to:detect-design 3. /jaan-to:detect-writing 4. /jaan-to:detect-product 5. /jaan-to:detect-ux

Platform: {platform2} ... (repeat for each platform)

After all platforms analyzed: /jaan-to:detect-pack"

Stop execution (orchestration mode)

If NO (single-platform): Display standard workflow list:

"To generate a full knowledge pack, run the detect skills first:

1. /jaan-to:detect-dev — Engineering audit
2. /jaan-to:detect-design — Design system detection
3. /jaan-to:detect-writing — Writing system extraction
4. /jaan-to:detect-product — Product reality extraction
5. /jaan-to:detect-ux — UX audit

Then run /jaan-to:detect-pack to consolidate."

Stop execution

Detect Platform Structure

If outputs exist, scan for platform suffixes to determine single vs multi-platform:

# Detect platforms by scanning for filename suffixes
platforms = set()
for domain in ['dev', 'design', 'writing', 'product', 'ux']:
  files = Glob(f"$JAAN_OUTPUTS_DIR/detect/{domain}/*-*.md")  # Files with dash suffix
  for file in files:
    # Extract platform from filename: "stack-web.md" → "web"
    # Pattern: {aspect}-{platform}.md where platform is everything after last dash
    filename = os.path.basename(file)
    if filename.count('-') >= 1:  # Has platform suffix
      platform = filename.split('-')[-1].replace('.md', '')
      platforms.add(platform)

# Also check for files WITHOUT suffix (single-platform)
for domain in ['dev', 'design', 'writing', 'product', 'ux']:
  files_no_suffix = Glob(f"$JAAN_OUTPUTS_DIR/detect/{domain}/*.md")
  for file in files_no_suffix:
    filename = os.path.basename(file)
    # Check if filename has NO platform suffix (e.g., "stack.md" not "stack-web.md")
    if '-' not in filename.replace('.md', ''):  # No dash in base name
      platforms.add('all')  # Single-platform marker
      break

platforms = list(platforms)

Handle detection results:

• No platforms detected → Something is wrong, no valid outputs found
• Only 'all' platform detected → Single-platform mode: consolidate all files into single pack
• Multiple platforms detected (excluding 'all') → Multi-platform mode: create per-platform packs + merged pack
• Mix of 'all' and platforms → Hybrid mode: treat 'all' as legacy single-platform alongside new multi-platform outputs

Display detection result:

PLATFORM DETECTION
------------------
Mode: {Single-platform / Multi-platform / Hybrid}
Platforms detected: {list}

If SOME but not all detect outputs exist:

Display:

"Found outputs for: {list of domains with outputs}. Missing: {list of domains without outputs}.

Continue with available outputs? (Results will be marked as partial) [y/n]"

If user declines, stop execution.

Step 1: Read All Detect Outputs

For each domain that has outputs, detect input mode and read accordingly:

Input Mode Detection

For each domain directory (detect/dev/, detect/design/, etc.):

1. Glob for individual aspect files (e.g., stack*.md, architecture*.md, tokens*.md)
2. If individual files found → input_mode = "full" — read all individual files (current behavior)
3. If only summary{suffix}.md found → input_mode = "light" — read summary file, extract findings_summary and overall_score from frontmatter
4. Track input mode per domain for use in subsequent steps:

Domain	Input Mode	Files Read
dev	full / light	{count} files or summary.md
design	full / light	{count} files or summary.md
writing	full / light	{count} files or summary.md
product	full / light	{count} files or summary.md
ux	full / light	{count} files or summary.md

Full-Mode Input: Expected Files

Domain	Directory	Expected Files
dev	$JAAN_OUTPUTS_DIR/detect/dev/	stack, architecture, standards, testing, cicd, deployment, security, observability, risks
design	$JAAN_OUTPUTS_DIR/detect/design/	brand, tokens, components, patterns, accessibility, governance
writing	$JAAN_OUTPUTS_DIR/detect/writing/	writing-system, glossary, ui-copy, error-messages, localization, samples
product	$JAAN_OUTPUTS_DIR/detect/product/	overview, features, value-prop, monetization, entitlements, metrics, constraints
ux	$JAAN_OUTPUTS_DIR/detect/ux/	personas, jtbd, flows, pain-points, heuristics, accessibility, gaps

Light-Mode Input: Summary Files

For domains with input_mode = "light", read summary{suffix}.md and extract:

• YAML frontmatter: findings_summary, overall_score, platform, target
• Executive summary text (for domain summary in consolidated output)

Step 2: Validate Universal Frontmatter

For each output file, validate required frontmatter fields:

• target.commit — MUST match current git HEAD (flag stale if mismatched)
• tool.rules_version — record for version compatibility
• confidence_scheme — MUST be "four-level"
• findings_summary — MUST have severity buckets (critical/high/medium/low/informational)
• overall_score — MUST be 0-10 numeric
• lifecycle_phase — MUST use CycloneDX vocabulary

Validation failures become findings in the consolidated output (severity: Medium, confidence: Confirmed).

Light-mode input handling: For domains with input_mode = "light", validate only the summary file frontmatter. Skip per-file validation (individual files don't exist).

Step 3: Aggregate Findings

Severity Buckets

Collect all findings_summary from each output file and aggregate into repo-wide totals:

Total Critical:      sum of all critical findings
Total High:          sum of all high findings
Total Medium:        sum of all medium findings
Total Low:           sum of all low findings
Total Informational: sum of all informational findings

Overall Score Formula

overall_score = 10 - (critical * 2.0 + high * 1.0 + medium * 0.4 + low * 0.1) / max(total_findings, 1)

Clamp result to 0-10 range.

If partial run (not all 5 domains), append "(partial)" to the score label.

Confidence Distribution

Count findings by confidence level across all domains:

• Confirmed: {n}
• Firm: {n}
• Tentative: {n}
• Uncertain: {n}

Step 4: Build Risk Heatmap

Create a domain x severity markdown table:

| Domain | Critical | High | Medium | Low | Info | Score |
|--------|----------|------|--------|-----|------|-------|
| Dev    | {n}      | {n}  | {n}    | {n} | {n}  | {s}   |
| Design | {n}      | {n}  | {n}    | {n} | {n}  | {s}   |
| Writing| {n}      | {n}  | {n}    | {n} | {n}  | {s}   |
| Product| {n}      | {n}  | {n}    | {n} | {n}  | {s}   |
| UX     | {n}      | {n}  | {n}    | {n} | {n}  | {s}   |
| **Total** | **{n}** | **{n}** | **{n}** | **{n}** | **{n}** | **{s}** |

For missing domains, show "not analyzed" in all cells.

If run_depth == "light": Skip Steps 5, 6, and 6a. Proceed directly to Step 7 (Present Consolidation Summary).

Note: For domains with input_mode = "light", Steps 2-4 use summary-level data (frontmatter scores and finding counts) instead of per-file data. Validation is limited to frontmatter presence check.

Step 5: Build Evidence Index (Source Map)

Collect ALL evidence IDs from all detect outputs and build a resolution index.

Reference: See ${CLAUDE_PLUGIN_ROOT}/docs/extending/detect-pack-reference.md sections "Evidence Index Table Format", "Evidence ID Parsing", "Evidence Validation Rules", and "Cross-Platform Evidence Linking" for table format, regex patterns, validation rules, and linking logic.

Step 6: Build Unknowns Backlog

Collect all findings with confidence <= Tentative (0.79 or below) and all "absence" evidence items.

For each unknown:

• Finding ID and title
• Current confidence level
• Domain
• "How to confirm" steps (what investigation would resolve the uncertainty)
• Explicit scope boundary (what this finding can and cannot claim)

Step 6a: Multi-Platform Consolidation (if applicable)

Only run this step if Step 0 detected multiple platforms.

If single-platform mode, skip to Step 7.

1. Aggregate Per-Platform Findings

For each detected platform, aggregate findings across all domains and calculate per-platform scores using the standard score formula.

Reference: See ${CLAUDE_PLUGIN_ROOT}/docs/extending/detect-pack-reference.md section "Per-Platform Aggregation Logic" for implementation details.

2. Build Cross-Platform Risk Heatmap

Build a platform x domain severity table with totals row.

Reference: See ${CLAUDE_PLUGIN_ROOT}/docs/extending/detect-pack-reference.md section "Cross-Platform Risk Heatmap Logic" for implementation and example table.

3. Identify Cross-Platform Findings

Extract findings with related_evidence field that link across platforms.

Reference: See ${CLAUDE_PLUGIN_ROOT}/docs/extending/detect-pack-reference.md section "Cross-Platform Findings Extraction" for implementation.

4. Deduplicate Shared Findings

Group cross-platform findings by canonical group ID and deduplicate. Store consolidated data (platform_findings, heatmap_table, deduplicated) for use in Step 8.

Reference: See ${CLAUDE_PLUGIN_ROOT}/docs/extending/detect-pack-reference.md section "Cross-Platform Deduplication Logic" for implementation.

---

HARD STOP — Consolidation Summary & User Approval

Step 7: Present Consolidation Summary

Reference: See ${CLAUDE_PLUGIN_ROOT}/docs/extending/detect-pack-reference.md section "Consolidation Summary Templates" for light mode, full single-platform, and full multi-platform display formats.

Present the consolidation summary using the appropriate template for current run_depth and platform mode.

"Proceed with writing consolidation files to $JAAN_OUTPUTS_DIR/detect/? [y/n]"

Do NOT proceed to Phase 2 without explicit approval.

---

PHASE 2: Write Output Files

Step 8: Write Output Files

Output directory logic:

# Determine output directory
if len(platforms) == 1 and 'all' in platforms:  # Single-platform
  output_dir = "$JAAN_OUTPUTS_DIR/detect/"
else:  # Multi-platform
  output_dir = "$JAAN_OUTPUTS_DIR/detect/pack/"

# Create directory if needed
os.makedirs(output_dir, exist_ok=True)

Stale File Cleanup

• If run_depth == "full": Delete any existing summary.md in $JAAN_OUTPUTS_DIR/detect/ (stale light-mode output).
• If run_depth == "light": Do NOT delete existing full-mode files.

If run_depth == "light": Write Single Summary File

Write one file: $JAAN_OUTPUTS_DIR/detect/summary.md

Reference: See ${CLAUDE_PLUGIN_ROOT}/docs/extending/detect-pack-reference.md section "Light Mode Summary File Structure" for required contents.

If run_depth == "full": Write Full Output Files

Single-Platform Mode

Write 4 output files to $JAAN_OUTPUTS_DIR/detect/:

File	Content
README.md	Knowledge index: metadata, domain summaries, overall score, links to all detect outputs
risk-heatmap.md	Risk heatmap table (domain x severity), top risks per domain
unknowns-backlog.md	Prioritized unknowns with "how to confirm" steps and scope boundaries
source-map.md	Evidence index: all E-IDs mapped to file locations

Multi-Platform Mode

Write to $JAAN_OUTPUTS_DIR/detect/pack/:

Per-Platform Packs (one per platform):

File	Content
README-{platform}.md	Platform-specific index with domain summaries for that platform only

Merged Pack (all platforms combined):

File	Content
README.md	Merged knowledge index with platform summary table and overall aggregated score
risk-heatmap.md	Cross-platform risk heatmap (platform x domain table) + cross-platform findings section
unknowns-backlog.md	All Tentative/Uncertain findings across all platforms, grouped by platform then domain
source-map.md	All evidence IDs from all platforms with platform column

README.md Structure (Single-Platform)

Reference: See ${CLAUDE_PLUGIN_ROOT}/docs/extending/detect-pack-reference.md section "README.md Structure (Single-Platform)" for full template. Includes: Overview, Domain Summaries (per-domain score + executive summary), Quick Links.

README.md Structure (Multi-Platform Merged Pack)

Reference: See ${CLAUDE_PLUGIN_ROOT}/docs/extending/detect-pack-reference.md section "README.md Structure (Multi-Platform Merged Pack)" for full template. Includes: Overview, Platform Summary table, Cross-Platform Findings, Per-Platform Details, Quick Links.

Each file MUST include universal YAML frontmatter.

---

Step 8a: Seed Update from Detection Data

Reference: See ${CLAUDE_PLUGIN_ROOT}/docs/extending/seed-reconciliation-reference.md for mapping tables, change categories, approval options, preservation rules, and report format.

Use consolidated detection results as source of truth to update all project seed files.

1. Read all seed files in $JAAN_CONTEXT_DIR/ (tech.md, team.md, integrations.md, boundaries.md, tone-of-voice.template.md, localization.template.md) — skip any that don't exist
2. Build proposed updates by cross-referencing detect outputs against each seed file using the mapping table and section anchors from the reference doc
3. Present diff-style summary per seed file using [UPDATE] / [ADD] / [STALE] categories — HARD STOP: require explicit approval ([y/all/n/pick])
4. Apply approved updates — edit seed files preserving section anchors, custom sections, and <!-- keep --> markers
5. Suggest /jaan-to:learn-add commands for detection findings that don't map to any seed file
6. Write reconciliation report to $JAAN_OUTPUTS_DIR/detect/seed-reconciliation.md

---

Step 9: Capture Feedback

"Any feedback on the knowledge pack? [y/n]"

If yes:

• Run /jaan-to:learn-add detect-pack "{feedback}"

---

ISO 25010 Quality Compliance

When aggregating detect outputs, map findings to ISO 25010 quality characteristics:

ISO 25010 Characteristic	Detect Sources	Signal
Functional Suitability	detect-dev (test coverage)	Test pass rate, coverage %
Performance Efficiency	detect-dev (architecture)	N+1 queries, connection pools
Compatibility	detect-dev (CI/CD)	Multi-platform support
Usability	detect-ux (UX audit)	Heuristic scores
Reliability	detect-dev (error handling)	Error handler coverage
Security	detect-dev (security scan)	Vulnerability counts
Maintainability	detect-dev (code quality)	Complexity, duplication
Portability	detect-dev (infrastructure)	Container, cloud-agnostic

Add "Quality Gate Readiness" section to consolidated output:

• Map aggregate scores to 4-tier gating model (auto-approve / lightweight / full / block)
• Reference /jaan-to:qa-quality-gate for detailed composite scoring

Skill Alignment

• Two-phase workflow with HARD STOP for human approval
• Evidence-based findings with confidence scoring
• Fork-isolated execution (context: fork)
• Output to standardized $JAAN_OUTPUTS_DIR path

Definition of Done

If run_depth == "light":

• Single summary.md written to $JAAN_OUTPUTS_DIR/detect/
• Universal YAML frontmatter with findings_summary and overall_score
• Risk heatmap table included (domain x severity)
• Per-domain executive summary (1-2 sentences each)
• Input mode table shows which domains provided full vs summary data
• Overall score calculated with formula
• Partial runs clearly labeled with coverage %
• "--full" upsell note included
• User approved output

If run_depth == "full":

Single-Platform Mode:

• All 4 output files written to $JAAN_OUTPUTS_DIR/detect/
• Universal YAML frontmatter in every file
• Risk heatmap shows domain x severity table
• Evidence index resolves all E-IDs to file locations
• No duplicate evidence IDs
• Unknowns backlog has "how to confirm" steps
• Overall score calculated with formula
• Partial runs clearly labeled with coverage %
• Frontmatter validation issues flagged
• User approved output
• Seed files updated from detection data (or user declined updates)
• Seed reconciliation report written to $JAAN_OUTPUTS_DIR/detect/seed-reconciliation.md

Multi-Platform Mode:

• Output files written to $JAAN_OUTPUTS_DIR/detect/pack/
• Per-platform packs created (README-{platform}.md for each platform)
• Merged pack created (README.md with platform summary table)
• Cross-platform risk heatmap shows platform x domain table
• Cross-platform findings section in heatmap (deduplicated via related_evidence)
• Evidence index includes platform column and handles both ID formats
• Evidence ID regex correctly parses E-DEV-001 and E-DEV-WEB-001 formats
• No duplicate evidence IDs (checked with platform awareness)
• Cross-platform evidence links validated (all related_evidence IDs exist)
• Unknowns backlog groups findings by platform, then domain
• Per-platform scores calculated correctly
• Overall weighted average score calculated from platform scores
• Platform detection logic executed in Step 0
• User approved output
• Seed files updated from detection data (or user declined updates)
• Seed reconciliation report written to $JAAN_OUTPUTS_DIR/detect/seed-reconciliation.md