standards-discover

name	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

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

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 .flowbit/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

1. Parse options from command arguments
2. Check prerequisites: Verify .flowbit/docs/ exists. If not, offer to run /flowbit-init first
3. Read existing standards from .flowbit/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 ask_user 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.

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 ask_user 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 ask_user with Accept/Modify/Skip options per finding.

  • If Modify: Incorporate the user's remarks into the standard's content immediately — update the description, examples, or rationale based on the feedback. Re-present the updated standard to the user for final confirmation. Only advance to the next finding once the user has confirmed the modified version (Accept) or chosen to Skip it. Do NOT carry unmodified content forward.
  • If Skip: Exclude from Phase 8 application.

• 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 ask_user 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.

BLOCKING GATE — MANDATORY: Do NOT proceed to Phase 8 until every finding has reached a terminal state:

• Accepted — original or modified content confirmed by the user
• Skipped — explicitly excluded by the user

A finding is NOT in terminal state if the user has provided remarks that have not yet been incorporated and re-confirmed. Advancing to Phase 8 while any finding is in a non-terminal state causes duplicate files and discards user remarks.

---

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."

NAMING CONVENTION — CRITICAL: Standard files MUST follow the docs-manager directory structure:

• Files live at standards/{category}/{topic}.md — e.g., standards/backend/api.md, standards/global/error-handling.md
• Topic filenames are short and noun-based: api.md, models.md, error-handling.md, validation.md
• Do NOT create files named backend-standards.md, api-standards.md, or any {category}-standards.md pattern
• Do NOT place files directly under standards/ root — always use the category subdirectory
• Before naming a new file, inspect existing files in .flowbit/docs/standards/{category}/ and follow the same naming pattern

For each approved standard (using the final, user-confirmed content from Phase 7):

1. 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 following the naming convention above. Add brief code examples only when they clarify the practice.
2. Check if file exists — If the target file already exists at standards/{category}/{topic}.md, use UPDATE (merge new findings with existing content). NEVER create a new file at a path that already has content — doing so produces duplicate files that cause user remarks to be discarded during INDEX.md regeneration.
3. Invoke docs-operator subagent via Task tool (subagent_type: flowbit-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.
4. After all standards applied, invoke docs-operator subagent via Task tool to regenerate INDEX.md. Wait for completion, then continue with step 5.
5. Invoke docs-operator subagent via Task tool to verify .github/copilot-instructions.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
.flowbit/docs/ missing	Offer /flowbit-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

# Full discovery (default)
/flowbit-standards-discover

# Quick scan (config files only, ~30-60s)
/flowbit-standards-discover --scope=quick

# Frontend standards only
/flowbit-standards-discover --scope=frontend

# High confidence, auto-apply
/flowbit-standards-discover --confidence=80 --auto-apply

# Skip external analysis (offline/no GitHub)
/flowbit-standards-discover --skip-external