| name | maister:standards-discover |
| description | Discover coding standards from project configuration files, code patterns, documentation, and external sources (PRs, CI/CD) |
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
- Parallel Execution: Launch discovery subagents concurrently for speed (~45-60s vs ~2-4min sequential)
- Evidence-Based: Every finding must cite specific files, line counts, or config rules as evidence
- Confidence Scoring: Multi-factor confidence based on source count, consistency, and explicitness
- Deduplication: Same standard found across sources merges into single finding with combined evidence
- Graceful Degradation: Skip unavailable sources (no gh CLI, no docs) without failing entire workflow
Input Parameters
| Parameter | Default | Description |
|---|
--scope | full | Discovery scope: full, quick, or any category name (baseline: global, frontend, backend, testing; custom categories also supported) |
--confidence | 60 | Minimum confidence threshold (0-100) for displaying findings |
--auto-apply | false | Auto-apply standards with confidence >= 90% without asking |
--skip-external | false | Skip GitHub PR analysis and CI/CD sources |
--pr-count | 20 | Number of recent merged PRs to analyze |
Scope determines which phases run:
| Scope | Config (P1) | Code (P2) | Docs (P3) | External (P4) |
|---|
full | Yes | Yes | Yes | Yes |
global | Yes | Yes (limited) | Yes | Yes |
frontend | FE configs | FE files | Yes | Yes |
backend | BE configs | BE files | Yes | Yes |
testing | Test configs | Test files | Yes | Yes |
quick | Yes | No | No | No |
[custom] | Relevant configs | Filtered files | Yes | Yes |
Custom scope values are matched against existing .maister/docs/standards/*/ directories and filter analysis to relevant files.
Phase Configuration
| Phase | Subject | activeForm |
|---|
| 1 | Plan discovery scope | Planning discovery scope |
| 2 | Analyze configuration files | Analyzing configuration files |
| 3 | Mine code patterns | Mining code patterns |
| 4 | Extract documentation standards | Extracting documentation standards |
| 5 | Analyze external sources | Analyzing external sources |
| 6 | Aggregate & deduplicate findings | Aggregating findings |
| 7 | Review findings with user | Reviewing findings |
| 8 | Apply approved standards | Applying standards |
| 9 | Generate summary report | Generating summary |
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
- Parse options from command arguments
- Check prerequisites: Verify
.maister/docs/ exists. If not, offer to run /maister:init first
- Read existing standards from
.maister/docs/INDEX.md to identify updates vs creates and avoid duplicates
- Display discovery plan showing scope, sources, and estimated time
- Get user confirmation via AskUserQuestion before proceeding
Phase 2-5: Parallel Discovery
CRITICAL: Launch all applicable subagents in ONE message for parallel execution.
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
STOP — Do NOT skip this step. Do NOT write prompts from memory.
Use the Read tool to load ONLY the reference files for phases you will execute:
| Phase | Condition | Read This File |
|---|
| 2: Config Analysis | Always | references/config-analyzer-prompt.md |
| 3: Code Patterns | scope != quick | references/code-pattern-prompt.md |
| 4: Documentation | scope != quick | references/docs-extractor-prompt.md |
| 5: External Sources | --skip-external not set | references/external-analyzer-prompt.md |
SELF-CHECK: Did you read the template files with the Read tool? If not, go back and read them now.
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.
❌ WRONG — launching one agent per message, waiting for result, then launching the next.
✅ CORRECT — launching ALL applicable agents (2–4 Task calls) in a SINGLE message.
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.
- Combine all findings from Phases 2-5
- Deduplicate by grouping on
category + standard_name — merge evidence and sources
- Calculate final confidence using multi-factor scoring from the reference
- Detect conflicts — flag contradictory standards (e.g., ESLint says semicolons, Prettier says no)
- Categorize into High (>= 80%), Medium (60-79%), Low (< 60%)
- 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
DELEGATION REQUIRED: Do NOT write standard files directly using Write/Edit tools. ALL file operations MUST go through the docs-operator subagent (Task tool).
SELF-CHECK before each file operation: "Am I about to write a file directly? STOP — invoke docs-operator via Task tool instead."
For each approved standard:
- Prepare content — Standard name, description, examples (preferred/avoid), rationale from evidence, source citations. Format each standard as a
### heading with 1-10 lines description (excluding code snippets). Group related standards into the same topic file. Add brief code examples only when they clarify the practice.
- Check if file exists — Determine create vs update action
- Invoke
docs-operator subagent via Task tool (subagent_type: maister:docs-operator) — Pass prepared content. For creates: new file. For updates: merge new findings with existing. Wait for completion, then continue with the next standard.
- After all standards applied, invoke
docs-operator subagent via Task tool to regenerate INDEX.md. Wait for completion, then continue with step 5.
- Invoke
docs-operator subagent via Task tool to verify CLAUDE.md integration — ensure standards directory is referenced. Wait for completion, then display the application summary.
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
| Situation | Strategy |
|---|
.maister/docs/ missing | Offer /maister:init, abort if declined |
| gh CLI unavailable | Skip PR analysis, continue with other sources |
| GitHub API rate limit | Skip PR analysis, note in report |
| Config file parse error | Skip that file, log warning, continue |
| No standards found | Suggest lowering threshold or checking specific scope |
| docs-manager fails | Offer retry/skip/cancel per standard |
| Subagent returns empty | Note in report, proceed with available findings |
Integration
| Integrates With | How |
|---|
docs-manager skill | Creates/updates standard files, regenerates INDEX.md |
implementation-plan-executor skill | Discovered standards immediately available via INDEX.md |
standards-update command | Complementary: discover = automated bulk, update = manual single |
Examples
/maister:standards-discover
/maister:standards-discover --scope=quick
/maister:standards-discover --scope=frontend
/maister:standards-discover --confidence=80 --auto-apply
/maister:standards-discover --skip-external
