$schema: ./schemas/suite-discovery-contract.schema.json
contract_id: rfc-suite-discovery
contract_version: 1.0.0
name: RFC suite discovery workflow
summary: Neutral pre-pack workflow for discovering the smallest clean RFC suite from a source corpus and packaging scaffold-ready inputs before any project pack is created.
governing_rules:
- id: discovery-before-pack
rule: Run suite discovery before project-pack scaffolding whenever suite boundaries, document ownership, or non-goals are not already fixed.
- id: authority-first
rule: Derive candidate suite boundaries from the authoritative corpus and observed/runtime surfaces, not from convenience module boundaries, prior summaries, or file trees alone.
- id: minimize-doc-count
rule: Prefer the smallest clean RFC suite that preserves clean ownership, clean-room implementability, reviewability, and reusable terminology.
- id: explicit-non-goals
rule: Keep subordinate material such as deployment guidance, runbooks, UI behavior, helper code, and illustrative-only fixtures merged, dependent, or out of scope unless it exposes an independent normative surface.
- id: structured-handoff
rule: The final discovery handoff must include a stable pack-scaffold-inputs block so pack generation consumes the suite decision instead of re-deriving it.
required_inputs:
system-name:
description: Human-readable system or project name under analysis.
authoritative-corpus:
description: Repositories, standards text, official docs, schemas, datasets, exported artifacts, or equivalent authoritative sources.
informative-material:
description: Orientation notes, explainer docs, prior drafts, issue threads, or other non-authoritative context.
observed-surfaces:
description: Runtime captures, APIs, traces, fixtures, exported files, or other observed behavior that reveals real structure.
authority-rule:
description: Explicit ranking to apply when sources disagree, or `unknown` when the workflow must infer and justify one.
artifact_families:
handoff:
publishable: false
description: Operator-facing discovery artifacts that can be reviewed and copied into downstream pack scaffolding.
must_include:
- final suite discovery brief
- pack scaffold inputs block
evidence:
publishable: false
description: Internal discovery artifacts that justify suite boundaries and preserve the reasoning trail.
must_include:
- source and authority map
- normative surface inventory
- rejected or merged candidate rationale
visibility_classes:
operator-shared:
description: Safe to share with the operator and the downstream pack-scaffolding step.
readable_by: [controller, corpus-analyst, suite-designer, pack-reviewer]
evidence-shared:
description: Internal discovery material shared across discovery roles.
readable_by: [controller, corpus-analyst, suite-designer, pack-reviewer]
roles:
controller:
purpose: Owns discovery scope, stage order, correction routing, and final handoff readiness.
can_read: [operator-shared, evidence-shared]
corpus-analyst:
purpose: Maps authoritative, informative, and observed sources and identifies candidate normative surfaces.
can_read: [operator-shared, evidence-shared]
suite-designer:
purpose: Clusters surfaces into the smallest clean RFC suite, assigns ownership, and states non-goals.
can_read: [operator-shared, evidence-shared]
pack-reviewer:
purpose: Checks that the discovery output is scaffold-ready, coherent, and explicit about unresolved metadata.
can_read: [operator-shared, evidence-shared]
artifact_types:
discovery-scope-note:
family: evidence
visibility: evidence-shared
description: Objective, corpus boundary, authority order, exclusions, and open questions for one discovery run.
corpus-map:
family: evidence
visibility: evidence-shared
description: Inventory of authoritative, informative, and observed sources plus gaps, contradictions, and authority notes.
normative-surface-inventory:
family: evidence
visibility: evidence-shared
description: Table of candidate normative surfaces, why they matter, likely owning document, and source anchors.
suite-boundary-decision:
family: evidence
visibility: evidence-shared
description: Candidate document boundaries, merges or rejections, dependency notes, and explicit non-goals.
pack-scaffold-inputs:
family: handoff
visibility: operator-shared
description: Stable structured input block for project-pack scaffolding.
suite-discovery-brief:
family: handoff
visibility: operator-shared
description: Final packaged discovery brief combining the system summary, surface inventory, suite decision, cross-document rules, and scaffold inputs.
stage_order:
- discovery-scope
- corpus-map
- surface-inventory
- suite-shaping
- handoff-packaging
stage_graph:
start_stage: discovery-scope
terminal_stages: [handoff-packaging]
pass_edges:
discovery-scope: [corpus-map]
corpus-map: [surface-inventory]
surface-inventory: [suite-shaping]
suite-shaping: [handoff-packaging]
handoff-packaging: []
stages:
discovery-scope:
id: discovery-scope
title: Fix the discovery objective and authority boundary
owner_role: controller
support_roles: [corpus-analyst, suite-designer]
depends_on_artifacts: []
may_consume_artifacts: []
entry_criteria:
- The system under analysis is named.
- The authoritative corpus, informative material, observed surfaces, and authority rule are provided or explicitly marked unknown.
- The operator agrees this run is discovery only and will not scaffold files yet.
advance_gate:
- The discovery-scope-note records the system name, corpus boundary, authority rule, and discovery-only objective.
- Unknown inputs, missing evidence, and operator decisions are explicit instead of implicit.
- The run can classify sources without reopening the objective.
outputs: [discovery-scope-note]
next_stages: [corpus-map]
repeatable: false
corpus-map:
id: corpus-map
title: Classify the source corpus and authority order
owner_role: corpus-analyst
support_roles: [controller]
depends_on_artifacts: [discovery-scope-note]
may_consume_artifacts: []
entry_criteria:
- The discovery scope note names the corpus and the authority rule.
- Authoritative, informative, and observed materials can be separated explicitly.
- Known coverage gaps, contradictions, and stale-surfaces are visible instead of hidden.
advance_gate:
- Every source class used by discovery is labeled authoritative, informative, or observed.
- Contradictions, stale docs, and unresolved gaps are captured rather than normalized away.
- The likely normative surfaces can be inventoried from the mapped corpus.
outputs: [corpus-map]
next_stages: [surface-inventory]
repeatable: true
surface-inventory:
id: surface-inventory
title: Inventory normative surfaces and likely owners
owner_role: corpus-analyst
support_roles: [suite-designer]
depends_on_artifacts: [discovery-scope-note, corpus-map]
may_consume_artifacts: []
entry_criteria:
- The authoritative corpus has been classified enough to identify real normative surfaces.
- Each candidate surface can be tied to evidence, not just a guessed module boundary.
- The workflow can separate core surfaces from subordinate or non-normative material.
advance_gate:
- The normative-surface-inventory lists the real algorithms, processes, formats, protocols, roles, and terminology domains that may need ownership.
- Each listed surface has source anchors or observed evidence.
- Subordinate or out-of-scope material is marked for merge, dependency, or exclusion.
outputs: [normative-surface-inventory]
next_stages: [suite-shaping]
repeatable: true
suite-shaping:
id: suite-shaping
title: Decide the smallest clean RFC suite
owner_role: suite-designer
support_roles: [controller, corpus-analyst]
depends_on_artifacts: [discovery-scope-note, corpus-map, normative-surface-inventory]
may_consume_artifacts: []
entry_criteria:
- The normative surface inventory is concrete enough to cluster by ownership and dependency.
- Weak candidate documents can be merged, rejected, or marked dependent with reasons.
- Cross-document terminology ownership, clean-room capabilities, and non-goals can be stated explicitly.
advance_gate:
- The suite-boundary-decision names the recommended deliverables and why they are the smallest clean suite.
- Rejected, merged, dependent, and out-of-scope candidates are explicitly dispositioned.
- Cross-document ownership, dependencies, clean-room capabilities, and non-goals are stable enough to feed pack scaffolding.
outputs: [suite-boundary-decision]
next_stages: [handoff-packaging]
repeatable: true
handoff-packaging:
id: handoff-packaging
title: Package discovery into scaffold-ready handoff artifacts
owner_role: pack-reviewer
support_roles: [controller, suite-designer]
depends_on_artifacts: [suite-boundary-decision]
may_consume_artifacts: [discovery-scope-note, corpus-map, normative-surface-inventory]
entry_criteria:
- The suite boundary decision is minimal, source-grounded, and explicit about non-goals.
- Remaining metadata questions are named instead of guessed.
- The downstream pack-generation headings can be filled without re-deriving suite shape.
advance_gate:
- The suite-discovery-brief packages the system summary, surface inventory, suite decision, and cross-document rules coherently.
- The final pack-scaffold-inputs block uses stable downstream headings and can be copied into the pack-generation prompt without reinterpretation.
- Any unresolved metadata is explicit enough to block guessing while still allowing the pack scaffold to proceed deliberately.
outputs: [pack-scaffold-inputs, suite-discovery-brief]
next_stages: []
repeatable: true
correction_policy:
rule: If a later stage exposes missing authority, fuzzy ownership, or a non-minimal split, reopen the earliest artifact that can resolve it and regenerate only the affected downstream discovery artifacts.
route_by_root_artifact:
discovery-scope-note: discovery-scope
corpus-map: corpus-map
normative-surface-inventory: surface-inventory
suite-boundary-decision: suite-shaping
pack-scaffold-inputs: handoff-packaging
suite-discovery-brief: handoff-packaging
rerun_scope: affected-downstream-stages-only
unresolved_questions_block_pack_scaffolding: true