Skill: Tech-Selection Convergence Method

The convergence process from analysis to an executable decision. Apply to any tech-selection scenario (language, framework, architecture, storage scheme, etc.). Triggered explicitly by the caller. Produces three independent files that reference each other.

When to use

• The user makes an explicit tech-selection request, such as "help me decide on tech" or "converge on what to use for X"
• The selection covers language, framework, architecture, storage scheme, or any multi-option technical decision
• The user needs a traceable, reversible decision under explicit constraints, not just an analysis

When NOT to use

• Two-option comparisons — use deep-comparison-analysis instead (it defines the comparison discipline that this skill's step 4 references)
• Single-option business-layer decisions that do not touch system-level behavior (data access patterns, business use-case layer additions) — these can proceed on a single option, but the rationale must be recorded in the supplementary notes
• Brainstorming or open-ended exploration before any decision direction is sought — come back once the user asks to converge

How to use

This method is a structured decision-convergence flow. Around a single selection topic, advance at the following cadence:

(1) Constraint completion — confirm team size, project state, priorities, existing decisions, and other preconditions
(2) Requirement review — check the requirement statement for implicit assumptions; list multiple reasonable interpretations for the decision-maker to choose from
(3) Industry survey — obtain industry-practice evidence by evidence level (L1 -> L2 -> L3 -> L4)
(4) Option comparison — list at least 2 candidate options; compare along 5 dimensions (complexity / experience / industry adoption / failure boundary / rollback cost)
(5) Direction confirmation — produce decision.md + core sections of supplementary-notes.md; the decision-maker confirms the direction
(6) Self-audit refinement — run the six-question self-audit on the chosen option; fold discovered issues into the cost section; produce the full supplementary-notes.md
(7) Impact review — examine the effect of this decision on other existing selections; produce an impact-analysis report
(8) Selection closure — after all selections are complete, in order: completeness check, global consistency review, dependency-version selection, tech-stack overview generation, code-review plan generation, unified implementation-reference generation

Each selection topic independently walks (1) -> (7). After all selections are complete, walk (8). Detailed rules for each step appear in the sections below.

Final deliverables

A complete selection-convergence flow (from the first selection to the last, all complete) produces the following files:

Core principle

The goal of tech selection is not "to find the optimal solution" but to make a traceable, reversible decision under constraints.

The selection process produces a large volume of analysis material (comparison tables, baseline data, pros-and-cons lists). That material is valuable for analysis but is noise for the decision-maker. The task of convergence is to translate the analysis output into three independent files, each addressed to a different reader.

Startup check: constraint and precondition completion

Before convergence begins, proactively confirm the following information with the user. Do not advance silently when information is incomplete — the user must confirm each precondition so they stay in control of the constraints.

Constraints to confirm:

Option-presentation rules (mandatory)

When presenting constraints / scope / interpretation options to the user, attach a plain-language explanation to each option so that a user without deep domain knowledge can still make a reasonable judgment.

Rules:

1. Use the option's description and preview fields to provide the explanation: description is a one-sentence summary; preview is a plain-language explanation (illustrate with project scenarios; describe what happens if chosen / not chosen)
2. Use plain language in the explanation; avoid unexplained jargon
3. Do not present "help me understand" as a standalone selectable answer — the explanation is embedded in the option's preview, so the user sees it naturally while browsing options
4. This rule applies to: constraint confirmation in the startup check, multi-interpretation choice in requirement review, and pre-selection comparison confirmation

The last point above is especially critical. If the user already has a default decision (e.g., "the UI uses framework X specifically"), mark it as an external constraint rather than as part of this selection's argumentation. The distinction:

BAD:  "Choose language Y because it supports framework X"   (treating an external constraint as if it were argumentation)
GOOD: "Choose language Y (mainstream community, mature ecosystem, high adoption rate). In addition, the team has decided to use framework X;
       X is only implemented by Y — this is an extra constraint, not a selection rationale."

Requirement review (mandatory)

The startup check is not just "collect constraints" — it also includes reviewing the requirement itself. The requirement the user states often hides unidentified assumptions. Advancing on the literal meaning may lock the option space to the wrong set.

High-risk keyword trigger list

When any of the following keywords appears in the requirement statement, trigger the three actions below:

Triggered actions (all three are required, no exceptions):

1. Implicit-assumption review — list all reasonable interpretations of the requirement; mark the implicit assumption of each interpretation; ask the user which interpretation to adopt. Do not let Claude choose an interpretation and advance on its own — the user must confirm
2. Industry-practice survey — follow the "industry-practice evidence levels" section
3. Option comparison — follow the "option-comparison requirements" section

Method for the implicit-assumption review

Decompose the user requirement into multiple interpretations, and surface the implicit assumption of each. For example:

User requirement: "Need minute-level keep-alive"

Interpretation A: the process must not be killed
        Implicit assumption: the connection must not be interrupted at all
        Corresponding option: foreground Service / process keep-alive

Interpretation B: short switch-out without loss + long switch-out with reconnect
        Implicit assumption: a ~5-second reconnect wait is acceptable
        Corresponding option: protocol-level keep-alive + state persistence + auto-reconnect

Interpretation C: any interruption is fully acceptable
        Implicit assumption: the user can recover manually
        Corresponding option: no keep-alive mechanism at all

-> Ask the user which interpretation to adopt; do not let Claude decide on its own

Prohibited behavior:

• Skipping this review and selecting an option directly is not allowed
• Presenting only one interpretation is not allowed (at least 2 must be listed)
• Treating "the strictest interpretation" as the default correct interpretation is not allowed

Prohibited behaviors

No circular argumentation

Each selection's argumentation must stand on its own; it cannot depend on other not-yet-confirmed decisions within the same selection.

Test method: remove the cited decision from the document and check whether the argumentation still holds. If it does not, it is circular argumentation.

Premise-source annotation: List every premise cited in this selection's argumentation, and annotate each item's source:

Source types:
  external constraint   — confirmed, already-decided outcome from the startup check
  intermediate conclusion of this selection — judgment derived within this selection's process
  unconfirmed assumption — information not yet confirmed by the user
  community common name — community naming or classification of a technology; not official wording
  official wording      — the actual wording in official documentation
  industry practice [level] — actual practice of similar products (L1/L2/L3/L4; see "Industry-practice evidence levels")

Rule: a premise annotated as "unconfirmed assumption" cannot serve as a basis for argumentation.

No information overload

The decision-maker does not need to see the full comparison matrix of candidate options, all data sources, or the pros-and-cons analysis of every technical detail. These are intermediate products of analysis, not inputs to the decision.

No analysis in place of decision

Listing pros and cons does not constitute making a decision. A decision is "choosing one option on the basis of known pros and cons under explicit constraints, and explicitly accepting its cost".

No silent assumptions

Do not assume constraints on your own when information is incomplete and advance on that basis. When information is missing, the user must be asked; only after an explicit answer may the flow continue.

No cross-selection inheritance of constraints

Each selection convergence starts independently and does not automatically inherit constraints or conclusions from previous convergences. Whether conclusions from previous convergences may serve as external constraints for this selection must be explicitly confirmed by the user during the startup check.

The executor is not allowed to infer relationships between selections on its own (e.g., "these two selections belong to the same round"). Dependencies or mutual exclusions between selections are defined by the user, not by the executor's judgment.

No treating community interpretation as official position

When citing official documentation, distinguish three layers:

• Official wording: the actual wording and terminology of the official documentation
• Community interpretation: the community's naming, classification, and extended interpretation of the official documentation
• Executor judgment: reasoning conclusions based on the above two

Any claim marked "officially recommended" or "officially not recommended" must be traceable to the original wording in the official documentation. If the citation is a community naming or classification (e.g., the community has labeled an architecture pattern, but the official documentation does not use that label), it must be marked as "community common name", not "official".

BAD:  "<vendor> officially recommends <community architecture label>"   (the vendor does not use that label; it is a community name)
GOOD: "<vendor> recommends <official wording> (community common name <label>)"
GOOD: "<vendor>'s official documentation does not use the <community architecture label> label"

No citation without verification

When citing a URL as evidence, if the citation supports a key claim that affects the direction of selection, the content of that URL must be read first to confirm the original wording matches the intended use, before writing it into the file.

For auxiliary information that does not affect the direction of selection, you may mark [pending verification] and defer it; but unverified content must not be presented in a definitive tone.

No treating community classification frameworks as objective fact

When the argumentation depends on classifying, categorizing, or naming a technical option (e.g., "this is MVVM", "this is MVC", "this is microservices", "this is reactive"), annotate the source of that classification framework. If the framework originates from the community rather than official or academic definitions, do not treat it as objective fact — it is a community cognitive tool and may simplify or distort reality.

Test method: when an "A vs B" opposition structure appears in the file, ask "who defined this opposition? Is the boundary between A and B drawn by officials/academia or agreed by the community?" If it is a community convention, mark it [community classification framework], and check whether there is an actual official practice that falls in between the opposition.

No hypothetical industry survey

When citing "industry practice" as argumentation, provide real sources per the "industry-practice evidence levels" section. Do not write expressions without specific sources such as "industry general practice", "mainstream solution", or "similar products usually".

Community discussions (Stack Overflow, Reddit, Medium, etc.) may not replace real practice evidence. Only when the user explicitly confirms that L4 is not needed may industry-practice evidence be omitted. See the "industry-practice evidence levels" section.

No skipping user-provided materials on the grounds of sufficient evidence

When the user has already provided materials (files in the project directory, reference materials proactively given in the conversation, specified URLs), review them one by one; do not skip any on the grounds that "other sources already provide sufficient evidence".

Reasoning: Different user-provided materials may cover different products, different architectural choices, and different scenarios. Unitree Go and Loona are two different competitors; their error-handling systems may be entirely different (one may use sealed classes, the other an Exception hierarchy). Skipping either means losing a perspective the user deliberately prepared.

Test method:

1. Before starting the selection, scan the project directory and conversation history, and list every user-provided material
2. Review, item by item, the parts of each material that are relevant to this selection
3. Only after review is complete may you judge "whether evidence is sufficient"
4. If after review you confirm a material is unrelated to this selection, you must explicitly record "[material name] reviewed, unrelated to this selection, reason: ..." in the supplementary notes — silent skipping is not allowed

Relationship to the L3 adoption rule: The full-adoption rule of L3 means "no basic verification at adoption time", not "may skip review". Review first, then adopt — the order may not be reversed.

Industry-practice evidence levels

Industry practice is the type of evidence that answers "what is reasonable in engineering", and complements official documentation (which answers "what is technically feasible"). For system-level behavior decisions (keep-alive, performance, battery, permissions, security, etc.), industry practice is critical evidence.

When surveying industry practice, obtain evidence in the following order. Only when a higher level is unavailable may you downgrade to the next level.

Evidence levels

Prohibited behaviors

1. No hypothetical industry survey — do not write expressions without specific sources such as "industry general practice is X" or "mainstream solution is Y"
2. No substituting L4 for L1/L2/L3 — community discussion may not replace real practice evidence
3. No vague sources — do not write expressions with ambiguous referents such as "a well-known App" or "in the open-source community"
4. No level-skipping downgrade — you must explicitly explain why L1/L2/L3 are unavailable before being allowed to use L4

Downgrade-decision flow

Start industry-practice survey
  |
  v
[Step A] Scan user-provided materials
  Scan the project directory and conversation history, and list all user-provided materials
  |- User material found -> mark as "pending review", proceed to step B
  +- No user material found -> proceed directly to step B
      |
      v
[Step B] Query L1 (product official channels: official technical blog, whitepaper, case study)
  |- Found -> adopt L1, annotate source
  +- Not found
      |
      v
      [Mandatory] Ask the user: is there L2 code-level evidence or L3 research material?
      (e.g., open-source code, APK decompilation, internal technical documentation, industry research report)
      |- User provides -> adopt L2 or L3, annotate source
      |              (L3 user-provided material is fully adopted without basic verification)
      +- User cannot provide
          |
          v
          Explicitly record "L1/L2/L3 all unavailable"
          |
          v
          Explain to the user: downgrade to L4 (community discussion)?
          |- User confirms need     -> adopt L4, annotate source + access date + downgrade reason
          |- User confirms not need -> this decision does not include industry-practice evidence;
          |                          explicitly record in supplementary notes "user confirms L4 industry-practice evidence not needed"
          +- User not explicit      -> do not advance; wait for user decision
      |
      v
[Step C] Mandatory review of user materials (regardless of step B outcome)
  If step A found user-provided materials:
  |- Review, item by item, the parts of each material relevant to this selection
  |- Fold the review results in as L3 evidence (full adoption)
  +- If after review you confirm a material is unrelated to this selection,
     you must record "[material name] reviewed, unrelated to this selection, reason: ..." in supplementary notes
  If step A found no user materials:
  +- Skip this step

Key rules:

• User-provided materials must be scanned at the start of the survey and reviewed by the end of the survey. Skipping review on the grounds of "sufficiency" of other evidence is not allowed.
• L3 is fully adopted, and Claude does not perform basic verification on user-provided materials — but the premise of "adoption" is "reviewed"; unreviewed materials may not be adopted and may not be skipped.
• When L1 is not found, the user must be proactively asked to provide L2/L3. Claude may not decide on a downgrade on its own.
• L4 is optional and must be explicitly confirmed by the user as to whether it is needed. Claude may not decide on L4 on its own.

Presentation requirements in supplementary-notes.md

Industry-practice evidence must be presented in a standalone table, not interleaved with other evidence.

### X.Y Industry-practice evidence

| Level | Source | Key fact | Verification method |
|-------|--------|----------|---------------------|
| L2    | <product> <version> <file path> | <specific fact> | <user-provided reverse-analysis report / open-source URL / ...> |
| ...   | ...    | ...      | ...                 |

Downgrade notes:
  - [If L4 was used, explain why L1/L2/L3 were unavailable]
  - [If industry-practice evidence was not used, state "user confirmed L4 not needed"]

Option-comparison requirements

Before entering "produce three files", you must list at least 2 candidate options and compare their costs, then select the main option. "Directly choosing a single option and advancing on all fronts" is not allowed.

Comparison discipline (analysis core): After listing the options, the rigor of the comparison itself follows the six-step discipline of the deep-comparison-analysis skill — split variables / compare fairly with controlled variables / strip external arguments / find essential differences / scale calibration / honest convergence. That discipline defines "how to compare rigorously" and is not repeated here (updates change only that one place and take effect globally); this section defines "what to compare" (the comparison dimensions below) and "what to produce" (the location of the comparison table). The two complement each other and do not conflict.

Trigger conditions (any one triggers)

• The requirement statement hits the "high-risk keyword trigger list" (see the startup check section)
• The decision involves system-level behavior (keep-alive, performance, battery, permissions, security, etc.)
• The user actively questions the already-chosen option
• The industry-practice survey result conflicts with the preliminary option

Business-layer decisions that do not hit the above conditions (e.g., data access pattern, business use-case layer addition) may proceed on a single option, but the rationale for "single-option advance" must be explicitly recorded in the supplementary notes.

Comparison dimensions

Each candidate option must be expanded along the following dimensions:

Output location

Add a standalone subsection "candidate-option comparison" in supplementary-notes.md, presented as a table:

### X.Z Candidate-option comparison

| Dimension              | Option A: <name> | Option B: <name> | ... |
|------------------------|------------------|------------------|-----|
| Implementation complexity | ...              | ...              | ... |
| User-experience impact    | ...              | ...              | ... |
| Industry adoption         | [L2: ...] / none | [L1: ...] / none | ... |
| Failure boundary          | ...              | ...              | ... |
| Rollback cost             | ...              | ...              | ... |

Chosen option: <A/B/...>
Choice rationale: <concrete judgment based on the comparison>

Prohibited behaviors:

• Presenting only one option is not allowed (at least 2 are required)
• Treating "main option" and "do-nothing option" as a comparison is not allowed — "do-nothing" is a degenerate state with no option, not a real candidate
• Leaving the "Industry adoption" dimension blank or writing "none" by default is not allowed — you must first proactively survey per the "industry-practice evidence levels" section
• Exception: If L1/L2/L3 are all unavailable, and the user explicitly confirms that L4 is not needed this time, you may write "none (user confirms L4 industry-practice evidence not needed)". This exception must explicitly declare the downgrade path; silent blank entries are not allowed

Cross-selection impact review (mandatory)

After each selection convergence is complete, you must proactively review the impact of this decision on other existing selection decisions. "Producing only this selection's two files and ignoring global consistency" is not allowed.

Trigger condition

Executed immediately after stage 2 (self-audit complete, full supplementary-notes.md output). Whether or not this selection cites conclusions from other selections as external constraints, the review must be performed — a one-way citation does not cause a conflict, but other selections may depend in reverse on this selection's intermediate conclusions.

Review scope

Scan the existing other selection decision files item by item (decision.md and supplementary-notes.md; implementation-reference.md does not need to be reviewed). For each other selection, answer:

1. Does any decision entry of that selection conflict with this new decision? — Direct conflict (opposite conclusions) or indirect conflict (premise changed by this decision)
2. Is any cost / failure condition of that selection changed by this decision? — The originally listed cost no longer exists, or the failure condition is now automatically satisfied
3. Does the argumentation of that selection cite technologies involved in this decision? — If so, check whether the citation still holds

Output form

The cross-selection impact review does not modify other selections' files; it only outputs an impact-analysis report to the user, who decides whether to revise the other files. Reasoning: selection files represent "the decision snapshot at that time"; frequent passive revision breaks the traceability of decisions; the user should proactively assess whether to trigger revision of other selections.

Output format:

# Impact review of the current selection on other decisions

## List of selections scanned
- Selection A: <file name>
- Selection B: <file name>
- ...

## Impact on <selection A decision>

### Direct conflicts (must revise)
- Decision item X: original text "..." conflicts with the new decision conclusion "..."
  - Conflict level: high / medium / low
  - Suggested handling: <must revise / suggest revise / defer revise>

### Indirect impacts (suggest revise)
- Constraint and cost item Y: original "..." is invalidated by the new decision
  - Suggested handling: <must delete / replace with new content>

### Pros and cons analysis
- Advantage of the new decision on <selection A>: ...
- Cost of the new decision on <selection A>: ...

### No impact
- <If a selection is entirely unaffected, state "no impact">

## Impact on <selection B decision>
...

## Revision-suggestion summary
| Selection | File | Revision content | Priority |
|-----------|------|------------------|----------|
| Selection A | decision.md | Rewrite item 3 | Must |
| Selection A | supplementary-notes.md | Delete section 4.2 | Must |
| ...        | ...  | ...              | ...      |

Prohibited behaviors:

• Skipping the cross-selection impact review and proceeding directly to the next selection is not allowed
• Outputting only "no impact" without showing the scan process is not allowed (the list of selections scanned must be listed)
• Actively modifying other selection files is not allowed — revision is allowed only after the user confirms
• Treating "revising other selection files" as an unfinished item of this selection convergence is not allowed — this selection ends with the full supplementary-notes.md output + the impact-review report

The three files

Produce three independent files that reference each other. implementation-reference.md is deferred and generated uniformly after all selections end; a single selection outputs only decision.md and supplementary-notes.md.

File 1: Decision summary (for the decision-maker)

Length: One paragraph to half a page. Readable on its own, with no dependency on the other two files.

Format: Strict three-part form ——

Requirement: [one sentence describing the problem to solve]
Decision:   [what was chosen, what was not chosen — numbered list, one sentence per item + optional 1-2 sentence rationale]
Constraints and costs: [the constraints of this decision, the confirmed costs, the conditions that trigger re-evaluation]

Content-attribution boundary (mandatory):

Judgment principle: If, after removing a table/list, the reader can still agree/disagree with "what is chosen, what is not chosen", then that table/list belongs in supplementary-notes.md.

Principles:

• Write only the decision and costs; do not write the argumentation process, do not write specification details
• Data appears only when supporting cost quantification (e.g., "~79% of apps use", "iOS migration 25-40 person-days")
• No code, file paths, build configuration, module structure, or specific step numbers
• No detailed tables (state-machine tables, error-handling tables, rule tables, etc. -> supplementary-notes.md)
• After reading this paragraph, the reader can make an "agree/disagree" judgment

File 2: Supplementary notes (for decision-makers or technical leads who need to understand the reasons)

Length: 1-3 pages. Opens with a citation of file 1 as a summary.

Format: Organized by selection dimension; each dimension contains ——

• Evidence table: facts + data + source link
• Reasons for not choosing an option (brief, no more than two lines)
• Expanded explanation of costs

Append self-audit results at the end: Self-audit of this selection's option (per the option self-audit six questions), as auxiliary evidence for the decision-maker to assess the option's maturity. Real problems found in the self-audit must be written into the cost section, not appearing only in the self-audit and disappearing from the file.

Handling of missing data:

• Cite data with a source normally
• Mark claims without clear data as [no clear data found yet, to be supplemented]; do not present estimates as definitive data
• The user may hold internal data or industry experience to fill these gaps

Principles:

• Attach a source link to every data-backed claim
• No specific implementation details (module structure, code examples, configuration files)
• Keep the narrative line "why this choice", not "how to implement"

File 3: Implementation reference (for the engineer doing the implementation)

Generation timing: implementation-reference.md is generated uniformly after all selections converge. A single selection does not output implementation-reference.md.

Length: Unlimited. Opens with a citation of file 2 as background.

Format: Organized by implementation steps ——

• Module structure / directory tree
• Build configuration example
• Step-by-step operations (down to file path and change content)
• Migration checklist (if cross-stage migration is needed)
• Common violations and corrections table

Principles:

• This file does not participate in the decision; it only serves implementation
• May contain code, configuration, dependency lists
• Must enable an engineer who did not participate in the decision process to complete the implementation by following the document
• Implementation references of each selection reference each other (e.g., the persistence implementation reference cites the ConnectionStateStore of the cross-module-communication implementation reference)

Progressive output (mandatory)

The three-file output is split across multiple stages. implementation-reference.md is deferred and generated uniformly after all selections end; a single selection outputs only decision.md and supplementary-notes.md.

Stage 1: Direction confirmation (within this selection)

Output content:

• decision.md (full three-part form)
• Core sections of supplementary-notes.md: evidence, not-chosen options, cost expansion, candidate-option comparison, industry-practice evidence

Do not output:

• implementation-reference.md (generated uniformly after all selections end)
• Self-audit results of supplementary-notes.md (self-audit is done in stage 2)

Purpose: Let the user confirm at the "direction" level. If the option is reversed, the rewrite cost is minimal.

Stage 2: Self-audit confirmation (within this selection)

After the user confirms the direction in stage 1, output:

• Full version of supplementary-notes.md (including self-audit results)

Do not output:

• implementation-reference.md

Trigger condition: The user explicitly states "direction confirmed" or has no objection to decision.md. If the user objects to the direction, return to stage 1 and redo; do not enter stage 2.

Stage 3: Cross-selection impact review (triggered immediately after this selection converges)

Execute the flow in the "Cross-selection impact review (mandatory)" section, and output an impact-analysis report on other existing selections.

The user decides whether to revise other selection files.

Stage 3.5: Selection-completeness check and global-consistency review (triggered after all selections are complete)

Trigger condition: The user explicitly states "all selections are complete" or "there are no more selections". Must be completed before entering stage 4 (implementation-reference generation).

Split into two steps, executed in order:

Step A: Omission check

Scan the project requirements, identify selection dimensions that may have been omitted. Output an omission-analysis report to the user.

Output format:

# Selection-completeness check report

## Completed selections (N)
- [List all completed selections]

## Possibly omitted selections

| Selection topic | Importance | Description | Reasoning |
|-----------------|------------|-------------|-----------|
| XXX             | High/Medium/Low | One sentence describing what problem this selection solves | Why it may be needed |
| YYY             | ...        | ...         | ...       |

## Dimensions that do not need a standalone selection
- [List dimensions already covered, and by which selection]

Bases for omission identification:

• Scan the requirement statement for technical dimensions involved but not independently selected
• Check whether the constraints and costs of existing selections cite technologies not independently selected
• Cross-reference the technical dimensions involved in similar apps

After user confirmation:

• User confirms there are omissions -> return to stage 1 to supplement the selection
• User confirms no omissions -> proceed to step B

Step B: Global-consistency review

Read every selection's decision.md and supplementary-notes.md file by file, and check for:

1. Direct conflict: the conclusions of two selections contradict each other
2. Premise invalidation: a premise of selection A's argumentation is overturned by selection B's conclusion
3. Terminology inconsistency: the same concept has different names in different selections
4. Cost omission: a linkage-revision suggestion of some selection was recorded but not executed

Output format:

# Global-consistency review report

## Review scope
- Scanned N selections' decision.md and supplementary-notes.md

## Conflicts / inconsistencies

| Selection A | Selection B | Conflict type | Specific description | Suggested handling |
|-------------|-------------|---------------|----------------------|--------------------|
| XXX         | YYY         | Premise invalidation | A cited Mutex, but B decided not to use Mutex | Modify A supplementary notes |
| ...         | ...         | ...           | ...                  | ...                |

## Selections without conflicts
- [List selections confirmed to have no conflicts]

## Revision requests
| File | Revision content | Reasoning |
|------|------------------|-----------|
| XXX supplementary-notes.md | Modify section Y | Align with ZZZ selection |

After user confirmation:

• User agrees to revise -> execute the revision, ensure all files are consistent
• User disagrees -> record the disagreement; do not force modification
• Only after revisions are complete may you proceed to stage 3.5.5

Stage 3.5.5: Dependency-version selection (after global-consistency review, before tech-stack overview)

Trigger condition: Stage 3.5 step B (global-consistency review) passes, and the user confirms the revisions are complete.

Reasoning: All technical selections have converged and consistency is confirmed; only at this point is the precondition for locking versions available — version selection requires knowing the full dependency list and their compatibility constraints. Version locking must be done before the tech-stack overview because the overview document contains the dependency-version list.

Input: Dependencies referenced in all selections' decision.md and supplementary-notes.md.

Flow:

1. Dependency-list collection: Extract all third-party dependencies from all decision files; annotate each dependency's source selection
2. Official-recommended version query: For each dependency, query the L1 official source (official documentation, Release Notes, Maven Central) to determine the current officially recommended version
3. Version-compatibility verification: Verify the mutual compatibility of the version combination, with focus on:
   • Language / compiler <-> main framework <-> annotation processor / plugin — the three-version chain
   • Build tool <-> language-version requirements
   • Dependency-injection framework <-> main framework version constraints
   • Framework BOM / alignment mechanism <-> language compatibility
   • Annotation processor <-> compiler-plugin version matching
4. Deprecated-library detection: Check whether any dependency has been officially deprecated or stopped being maintained; identify replacement options
5. Output: dependency-version-selection.md (with version table, compatibility-verification results, failure conditions)

After completion: Proactively ask the user whether to confirm; only after confirmation may you proceed to stage 3.6. Automatic advance is not allowed.

Stage 3.6: Tech-stack and architecture-overview generation (after all selections are complete, before implementation reference)

Trigger condition: Stage 3.5 step B (global-consistency review) passes, and the user confirms the revisions are complete.

Input: All selections' decision.md and supplementary-notes.md.

Output: A single file tech-stack-and-architecture-overview.md, containing the following (trim as needed):

Principles:

• Describe "what it is", not "how to implement" (no code, configuration, specific step numbers)
• Annotate the source decision file for each claim
• The architecture diagram must cover all layers from UI to persistence, including cross-cutting concerns

After completion: Proactively ask the user whether to confirm; only after confirmation may you proceed to stage 3.7. Automatic advance is not allowed.

Stage 3.7: Code-review-plan generation (after tech-stack overview, before implementation reference)

Trigger condition: Stage 3.6 output has been confirmed by the user.

Input: Items marked "mandatory" and "prohibited" in all selections' decision.md and supplementary-notes.md.

Output: A single file code-review-plan.md, containing:

Principles:

• Each check item must annotate its source decision
• Distinguish "must-check (every PR)" from "review per trigger condition"
• "Prohibited" rules are listed directly; argumentation is not required

After completion: Proactively ask the user whether to confirm; only after confirmation may you proceed to stage 4 (implementation-reference generation). Automatic advance is not allowed.

Stage 4: Unified implementation-reference generation (triggered after all selections end)

Trigger condition: The user explicitly states "all selections are complete" or proactively requests "generate implementation reference".

Output content:

• Batch-generate implementation-reference.md for all completed selections
• Implementation references cross-reference each other, with unified directory structure, unified file-naming conventions, and unified code style

Reasoning

• The implementation reference is the file with the largest investment (code examples, directory structure, configuration, violation tables)
• Implementation details across selections intersect (e.g., the implementation of the data-access layer is referenced by the business layer; cross-module state management is referenced by the persistence layer); writing them separately leads to inconsistent style and duplicated effort
• Not generating an implementation reference at the end of a single selection lets the user advance to the next selection faster
• If the direction of a selection is overturned by a later selection and the implementation reference has not yet been written, the rewrite cost is zero

Example (anti-pattern):

BAD:  Claude generates implementation-reference.md at every selection convergence
      A later selection overturns the direction of this selection
      -> implementation reference rewrite (including ~500 lines of implementation code)

GOOD: Claude outputs only decision.md + supplementary-notes.md (with self-audit) per single selection
      A later selection overturns the direction -> rewrite decision + supplementary notes; implementation reference not yet written
      After all selections converge, generate implementation references uniformly, with consistent cross-references

Proactive prompt after stage 2 ends (mandatory)

After the stage-2 output is complete, proactively ask the user for the next action. Do not default to advancing to the next selection; do not default to starting implementation-reference generation.

Prompt content:

This [<selection name>] selection has converged.
The cross-selection impact-review report has been output (e.g., impact on <selection X>, <selection Y>).

Choose the next step:
1. Revise affected existing selection decisions (if needed)
2. Start the next selection
3. All selections are complete (enter completeness check and global-consistency review)

Prohibited behaviors:

• Automatically generating implementation-reference.md within a single selection is not allowed
• Skipping the cross-selection impact review and proceeding directly to the next selection is not allowed
• Not asking the user for the next action after stage 2 ends is not allowed

Convergence process

Input: analysis material (comparison tables, baseline data, pros-and-cons lists)
       user-provided constraints (obtained through the startup check)

  +---------------------------------+
  | Step 1: Constraint and precondition completion
  |   Confirm constraints with the user, identify external premises
  |   Distinguish "this selection's argumentation" from "external constraint"
  +---------------+-----------------+
                  |
                  v
  +---------------------------------+
  | Step 2: Requirement review (mandatory)
  |   Check whether the requirement hits "high-risk keywords"
  |   If hit: list all reasonable interpretations
  |   Ask the user which interpretation to adopt
  |   Do not let Claude select an interpretation on its own
  +---------------+-----------------+
                  |
                  v
  +---------------------------------+
  | Step 3: Industry-practice survey (mandatory)
  |   Obtain evidence in order L1 -> L2 -> L3 -> L4
  |   When L1 is not found, must ask the user to provide L2/L3
  |   L4 is explicitly confirmed by the user as to whether to adopt
  +---------------+-----------------+
                  |
                  v
  +---------------------------------+
  | Step 4: Option comparison (mandatory)
  |   List at least 2 candidate options
  |   Compare along 5 dimensions (including industry adoption)
  |   Confirmed by the user, or Claude chooses based on the comparison
  +---------------+-----------------+
                  |
                  v
  +---------------------------------+
  | Step 5: Independence test
  |   Does each decision's argumentation stand on its own?
  |   Remove circular references
  |   Mark external premises as constraints, not as argumentation basis
  +---------------+-----------------+
                  |
                  v
  +---------------------------------+
  | Step 6: Cost extraction
  |   What is each decision's confirmed cost?
  |   Under what conditions should it be overturned?
  |   Missing data marked [to be supplemented]
  +---------------+-----------------+
                  |
                  v
  +---------------------------------+
  | Step 7: Stage-1 output (mandatory)
  |   decision.md (full three-part form)
  |   Core sections of supplementary-notes.md
  |   (evidence, not-chosen options, costs, comparison,
  |    industry-practice evidence)
  |   [!] Do not output implementation-reference.md
  |   [!] Do not output self-audit results
  +---------------+-----------------+
                  |
                  v
         User confirms direction?
          |- No  -> return to steps 2-6 and redo
          +- Yes |
                  v
  +---------------------------------+
  | Step 8: Self-audit
  |   Answer the option self-audit six questions
  |   Fold discovered problems into the cost section
  +---------------+-----------------+
                  |
                  v
  +---------------------------------+
  | Step 9: Stage-2 output
  |   Full version of supplementary-notes.md (with self-audit)
  |   [!] Do not output implementation-reference.md
  +---------------+-----------------+
                  |
                  v
  +---------------------------------+
  | Step 10: Cross-selection impact review (mandatory)
  |   Scan all existing selection decisions
  |   Item by item analyze direct conflicts / indirect impacts /
  |    whether citations still hold
  |   Output an impact-analysis report (do not modify files)
  +---------------+-----------------+
                  |
                  v
  +---------------------------------+
  | Step 11: Proactively ask the user for the next action
  |   Options:
  |    a. Revise affected existing selections
  |    b. Start the next selection
  |    c. All selections are complete
  +---------------+-----------------+
                  |
                  v
  +---------------------------------+
  | Step 12 (only after all selections end):
  |   Selection-completeness check (omission analysis)
  |   Scan requirements / existing selections / similar apps
  |   Identify possibly-omitted selection dimensions
  |   Output an omission-analysis report to the user
  +---------------+-----------------+
                  |
                  v
         User confirms there are omissions?
          |- Yes -> return to step 1 to supplement the selection
          +- No  |
                  v
  +---------------------------------+
  | Step 13: Global-consistency review
  |   Read every decision + supplementary notes file by file
  |   Check direct conflicts / premise invalidation / terminology inconsistency
  |   Check whether linkage-revision suggestions have been executed
  |   Output conflict report + revision requests
  +---------------+-----------------+
                  |
                  v
         User agrees to revise?
          |- Yes -> execute revisions, ensure consistency
          +- No  -> record disagreement
                  |
                  v
  +---------------------------------+
  | Step 14: Dependency-version selection
  |   Collect all dependencies and query officially recommended versions
  |   Verify version-combination compatibility
  |   Detect deprecated libraries and identify replacements
  |   Output: dependency-version-selection.md
  +---------------+-----------------+
                  |
                  v
         User confirms?
          |- Has changes -> revise and re-confirm
          +- Confirmed |
                       v
  +---------------------------------+
  | Step 15: Tech-stack and architecture-overview generation
  |   Aggregate all selection conclusions into a unified architecture document
  |   Includes tech-stack table / architecture diagram / data flow / state machine
  |   Output: tech-stack-and-architecture-overview.md
  +---------------+-----------------+
                  |
                  v
         User confirms?
          |- Has changes -> revise and re-confirm
          +- Confirmed |
                       v
  +---------------------------------+
  | Step 16: Code-review-plan generation
  |   Extract all selections' mandatory / prohibited rules
  |   Organize as a tiered review checklist
  |   Output: code-review-plan.md
  +---------------+-----------------+
                  |
                  v
         User confirms?
          |- Has changes -> revise and re-confirm
          +- Confirmed |
                       v
  +---------------------------------+
  | Step 17: Unified generation of all implementation-reference.md
  |   Cross-reference consistent / unified style
  +---------------------------------+

The caller decides whether to iterate based on actual conditions. A finding at any step may require going back to earlier steps and reprocessing.

Effect of constraints on selection

Writing failure conditions

Every decision must be accompanied by a failure condition. Format:

When [a specific, observable condition] is satisfied, re-evaluate [specific decision].

Valid failure conditions:

• "When a dedicated <platform> developer joins, re-evaluate whether to introduce a cross-platform scheme" (observable, with a time anchor)
• "When <some cross-platform tech> supports <specific capability> cross-platform, re-evaluate the cross-platform strategy" (technical condition is explicit)

Invalid failure conditions:

• "When the team becomes familiar" (vague; cannot judge when satisfied)
• "When the technology matures" (what counts as mature? no standard)
• "When needed" (equivalent to no condition)

Quality check

Before convergence is complete, check item by item:

Option self-audit six questions (used in convergence step 8)

After proposing any option, answer the following questions:

1. What file does the first step change? Down to the file path, method name, and what to change. If you cannot answer, the option is not executable.
2. How many existing files does the change affect? More than 30% is a rewrite, not an improvement.
3. What new problems does the new option introduce? Each option solves some problems while introducing new ones; list them honestly.
4. Can a newcomer three years later understand it? If an architect needs to be asked, there is too much tacit knowledge.
5. Can doing 20% capture 80% of the benefit? If not, the problem is not at the architecture level.
6. Under what conditions do we overturn it? If you cannot write a failure condition, the choice has been treated as a belief.