skillpanel/maister/standards-discover

Standards Discovery Skill

Analyzes multiple project sources in parallel to discover coding standards, conventions, and best practices. Aggregates findings with confidence scoring, presents for user approval, and applies approved standards via docs-manager skill.

Core Principles

1. Parallel Execution: Launch discovery subagents concurrently for speed (~45-60s vs ~2-4min sequential)
2. Evidence-Based: Every finding must cite specific files, line counts, or config rules as evidence
3. Confidence Scoring: Multi-factor confidence based on source count, consistency, and explicitness
4. Deduplication: Same standard found across sources merges into single finding with combined evidence
5. Graceful Degradation: Skip unavailable sources (no gh CLI, no docs) without failing entire workflow

Input Parameters

Scope determines which phases run:

Custom scope values are matched against existing .maister/docs/standards/*/ directories and filter analysis to relevant files.

Phase Configuration

Task Tracking: At start of Phase 1, use TaskCreate for all phases above (pending). Set dependencies: Phases 2-5 blocked by Phase 1 (they run in parallel after planning). Phase 6 blocked by Phases 2-5. Phases 7-9 sequential. At each phase start: TaskUpdate to in_progress. At each phase end: TaskUpdate to completed. For phases skipped due to scope (e.g., Phases 3-4 when --scope=quick), mark completed with metadata: {skipped: true, reason: "scope=quick"}.

Execution Workflow

Phase 1: Planning & Initialization

1. Parse options from command arguments
2. Check prerequisites: Verify .maister/docs/ exists. If not, offer to run /maister:init first
3. Read existing standards from .maister/docs/INDEX.md to identify updates vs creates and avoid duplicates
4. Display discovery plan showing scope, sources, and estimated time
5. Get user confirmation via AskUserQuestion before proceeding

Phase 2-5: Parallel Discovery

Launch all applicable subagents in one message so they run in parallel.

Step 1: Determine which phases to run based on scope and flags.

Step 1.5: Create temp output directory — Run mktemp -d via Bash to create a unique temp directory for this invocation. Store the path (e.g., /tmp/abc123). Each subagent will write its results to a dedicated file in this directory: {tmpdir}/config.yml, {tmpdir}/code.yml, {tmpdir}/docs.yml, {tmpdir}/external.yml.

Step 2: Read prompt templates

Read the template for each phase you will run — they define the YAML output schema the aggregation step depends on:

Step 3: Adapt templates — Replace [scope], [confidence], and other placeholders with actual values. Replace the [output_file] placeholder in each template with the actual temp file path for that phase (e.g., {tmpdir}/config.yml).

Step 4: Launch subagents in parallel — Use the Task tool with subagent_type: general-purpose for each phase.

Step 5: Wait for ALL subagents to complete, then read each temp file using the Read tool to collect findings.

Step 6: Display progress — Show count of findings per phase.

Phase 6: Aggregation & Deduplication

Read references/aggregation-strategy.md for confidence scoring methodology.

1. Combine all findings from Phases 2-5
2. Deduplicate by grouping on category + standard_name — merge evidence and sources
3. Calculate final confidence using multi-factor scoring from the reference
4. Detect conflicts — flag contradictory standards (e.g., ESLint says semicolons, Prettier says no)
5. Categorize into High (>= 80%), Medium (60-79%), Low (< 60%)
6. Filter by --confidence threshold

Display aggregation summary: total raw findings, unique standards, conflicts detected.

Phase 7: User Review & Approval

Step 1: Present full summary table — Before any approval prompts, output ALL findings in a table grouped by confidence level. Each group has a header with count:

### High Confidence (>=80%) — 5 standards
 
| # | Standard | Category | Score | Sources | Description |
|---|----------|----------|-------|---------|-------------|
| 1 | no-semicolons | global | 92 | config, code, docs | Omit semicolons in all JS/TS files |
| 2 | ... | ... | ... | ... | ... |
 
### Medium Confidence (60-79%) — 3 standards
...
 
### Low Confidence (<60%) — 2 standards
...
 
### Conflicts — 1 detected
| # | Standard | Conflict | Sources A | Sources B |

The Sources column lists all contributing sources for each finding (config, code, docs, PRs, CI, pre-commit). This gives users full visibility before making decisions.

Step 2: Approval flow — After the summary table:

• High confidence (>= 80%): Use AskUserQuestion offering batch approval ("Apply all N high-confidence standards") or individual drill-down review. For drill-down, show full detail per finding: all evidence items with source attribution, examples (preferred/avoid), and confidence score breakdown (which factors contributed how many points).

• Medium confidence (60-79%): Present each individually with full detail (evidence, examples, confidence breakdown). Use AskUserQuestion with Accept/Modify/Skip options per finding.

• Low confidence (< threshold): Show the summary table rows only. Offer to expand details or skip all.

• Conflicts: Present each conflict showing both sides with their evidence and sources. Use AskUserQuestion to resolve (pick side A, pick side B, skip, or custom).

If --auto-apply is set, automatically approve findings with confidence >= 90% and only prompt for the rest.

Phase 8: Application

Write standard files through the docs-operator subagent rather than Write/Edit, so INDEX.md and CLAUDE.md stay consistent with the files.

1. Prepare content for every approved standard — standard name, description, examples (preferred/avoid), rationale from evidence, source citations. Format each as a ### heading with a 1-10 line description (excluding code snippets); group related standards into one topic file; add brief code examples only where they clarify. Note create vs update for each target file.
2. Invoke the `docs-operator` subagent once via Task tool (subagent_type: maister:docs-operator) with all prepared standards, instructing it to apply each create/update (merging updates with existing content), then regenerate INDEX.md and confirm CLAUDE.md references the standards directory.

Display application summary: created count, updated count, total active.

Phase 9: Summary Report

Display final results:

• Sources analyzed (config files, code files sampled, docs parsed, PRs reviewed)
• Standards applied (created/updated counts by category)
• Standards skipped (low confidence, user declined)
• Next steps (review, commit, re-run schedule)

Error Handling

Integration

Examples

# Full discovery (default)
/maister:standards-discover
 
# Quick scan (config files only, ~30-60s)
/maister:standards-discover --scope=quick
 
# Frontend standards only
/maister:standards-discover --scope=frontend
 
# High confidence, auto-apply
/maister:standards-discover --confidence=80 --auto-apply
 
# Skip external analysis (offline/no GitHub)
/maister:standards-discover --skip-external