Create atlas-subtree-expansion-index-v1.md

2026-04-28 11:40:07 +00:00 · 2026-03-20 15:12:58 +08:00 · 2026-03-20 15:12:58 +08:00 · 1778e6b639
commit 1778e6b639
parent 60312c706a
1 changed files with 685 additions and 0 deletions
--- a/ProblemMap/Atlas/atlas-subtree-expansion-index-v1.md
+++ b/ProblemMap/Atlas/atlas-subtree-expansion-index-v1.md
@ -0,0 +1,685 @@
+<!--
+AI_NOTE_START
+
+Document role:
+This page is the public subtree expansion index for the Atlas document system.
+
+How to use this page:
+1. Read this page after the family mini-spec page and the boundary guide if you want to understand how subtree expansion is organized.
+2. Use this page to understand what counts as a subtree, what does not count as a subtree, and how subtree status should be read.
+3. Use this page as the public control page for subtree visibility, not as the final encyclopedia of every subtree.
+4. Do not use this page as a replacement for the frozen core, the fit registry, or the full repair-facing documents.
+
+What this page is:
+- A public subtree index
+- A subtree status map
+- A public expansion control page
+- A beginner-friendly bridge between family-level reading and later finer-grained public decomposition
+
+What this page is not:
+- Not the public homepage
+- Not the Atlas Hub
+- Not the full freeze document
+- Not the full subtree encyclopedia
+- Not the fit candidate registry
+- Not the first-fix manual
+- Not the output contract page
+- Not a claim that all Atlas subtrees are already fully expanded in public
+
+Reading discipline for AI:
+- Treat subtree reading as a finer layer than family, but not as a license for arbitrary over-segmentation.
+- Do not invent subtree names as if they were already stabilized public assets.
+- Preserve the difference between family, boundary, subtree, fit, overlay, and repair layers.
+- Use this page to understand public subtree status and expansion discipline, not to fabricate closure.
+- When subtree evidence is weak, remain at family level or boundary level rather than forcing a false detailed node.
+
+Relationship to neighboring docs:
+- Read after: [Atlas Family Mini-Specs](./atlas-family-mini-specs-v1.md) and [Atlas Boundary Decision Guide](./atlas-boundary-decision-guide-v1.md).
+- Read with: [Atlas Hub](./README.md) if you want the overall folder map and planned public decomposition list.
+- Read before: [Atlas Fit Candidate Registry v1](./atlas-fit-candidate-registry-v1.md) and [Atlas First Fix and Misrepair Discipline v1](./atlas-first-fix-and-misrepair-discipline-v1.md).
+- Pairs with: [Canonical Casebook v1](./canonical-casebook-v1.md), because the casebook may show case shapes while this page controls subtree visibility and status language.
+
+Freeze / patch status:
+- Current status: public decomposition layer
+- Safe to quote as: the public subtree expansion index and status-control page for Atlas
+- Not a claim of: silent rewrite of the frozen core or full public closure of every subtree
+
+AI_NOTE_END
+-->
+
+# Atlas Subtree Expansion Index 🌿
+
+## Problem Map 3.0 Troubleshooting Atlas
+> Quick links, subtree status language, and beginner-friendly public expansion control for the Atlas middle layer
+
+This page exists because the word **subtree** is easy to say, but easy to misuse.
+
+People often feel that a family-level view is still too coarse.  
+That instinct is sometimes correct.
+
+But the next step is not:
+
+invent more labels,  
+split endlessly,  
+or pretend that every local pattern already deserves a public node.
+
+The next step is subtree discipline.
+
+This page gives that discipline in a readable public form.
+
+It tells readers:
+
+- what a subtree is
+- what a subtree is not
+- why subtree expansion matters
+- how subtree status should be described
+- which parts of the Atlas currently have public subtree visibility
+- which parts are still open, partial, or not yet promoted
+
+This page is a control page, not a pile of improvised micro-labels.
+
+---
+
+## Quick Links 🚀
+
+If you are new, use these first.
+
+### I want the public introduction
+- [Problem Map 3.0 Troubleshooting Atlas](../wfgy-ai-problem-map-troubleshooting-atlas.md)
+
+### I want the folder control room
+- [Atlas Hub](./README.md)
+
+### I want the overall structure map first
+- [Atlas Structure Map](./atlas-structure-map-v1.md)
+
+### I want the family layer before this page
+- [Atlas Family Mini-Specs](./atlas-family-mini-specs-v1.md)
+
+### I want the boundary layer before this page
+- [Atlas Boundary Decision Guide](./atlas-boundary-decision-guide-v1.md)
+
+### I want the stable core after this page
+- [Atlas Final Freeze v1](./atlas-final-freeze-v1.md)
+- [Atlas Negative Space Report v1](./atlas-negative-space-report-v1.md)
+
+### I want examples while reading this page
+- [Canonical Casebook v1](./canonical-casebook-v1.md)
+
+### I want the next middle-layer pages after this one
+- [Atlas Fit Candidate Registry v1](./atlas-fit-candidate-registry-v1.md)
+- [Atlas First Fix and Misrepair Discipline v1](./atlas-first-fix-and-misrepair-discipline-v1.md)
+
+### I want the compact practical route-first layer
+- [Troubleshooting Atlas Router v1 Usage Guide](./troubleshooting-atlas-router-v1-usage.md)
+- [Troubleshooting Atlas Router v1 TXT Pack](./troubleshooting-atlas-router-v1.txt)
+
+---
+
+## Why this page exists
+
+The Atlas already has a family layer.
+
+That is necessary, but it is not always enough.
+
+Some cases clearly belong inside the same family while still needing a more precise public reading surface.  
+That is where subtree thinking becomes useful.
+
+But subtree work creates a risk.
+
+If done badly, it turns into:
+
+- arbitrary naming
+- uncontrolled splitting
+- pseudo-precision
+- silent drift away from the frozen structure
+- public pages that look detailed but do not actually help routing or repair safety
+
+So this page exists to prevent that drift.
+
+It creates a public index and a public status language for subtree work.
+
+That way, the Atlas can grow in a controlled way rather than becoming a jungle of improvised branches.
+
+---
+
+## Scope
+
+This page focuses on:
+
+- what counts as a subtree
+- subtree status categories
+- public subtree visibility rules
+- subtree expansion posture by family
+- what is currently public, partial, open, or not yet promoted
+- how readers should interpret absent subtree pages
+
+This page does **not** focus on:
+
+- full formal definitions of every subtree
+- complete node enumeration
+- fit promotion criteria in full
+- overlay rules in detail
+- full repair instructions
+- pairwise boundary logic beyond what is already needed for subtree control
+
+This page is a management layer for public subtree expansion.
+
+---
+
+## How to use this page
+
+Use this page in the following order.
+
+### Step 1
+Start with the family layer.
+
+Read:
+- [Atlas Family Mini-Specs](./atlas-family-mini-specs-v1.md)
+
+### Step 2
+If the family level still feels too broad, use the boundary layer.
+
+Read:
+- [Atlas Boundary Decision Guide](./atlas-boundary-decision-guide-v1.md)
+
+### Step 3
+Only after that, ask whether the case needs subtree-level treatment.
+
+Use this page to answer:
+- does a public subtree surface already exist here
+- is the area only partially expanded
+- is the area still open
+- should the case remain at family or boundary level for now
+
+### Step 4
+If subtree-level work is still justified, use later pages to control certainty and action:
+
+- [Atlas Fit Candidate Registry v1](./atlas-fit-candidate-registry-v1.md)
+- [Atlas First Fix and Misrepair Discipline v1](./atlas-first-fix-and-misrepair-discipline-v1.md)
+
+That order keeps subtree expansion disciplined.
+
+---
+
+## What counts as a subtree
+
+A subtree is a finer structural layer inside a family.
+
+It is more specific than a family, but it is not just any tiny symptom list.
+
+A public subtree should usually satisfy all of the following ideas:
+
+- it lives under a recognizable family surface
+- it sharpens routing in a useful way
+- it helps reduce confusion, not increase it
+- it has meaningful separation value from neighboring subtrees or neighboring family-level cases
+- it can support later fit or repair reasoning more safely than staying vague
+- it does not exist only because a label sounds convenient
+
+So a subtree is not a decorative detail.
+
+It is a meaningful branch that earns its place by improving clarity.
+
+---
+
+## What does not count as a subtree
+
+The following things should not automatically be treated as stable subtree material.
+
+### 1. A random symptom bundle
+A list of symptoms is not yet a subtree.
+
+### 2. A one-off phrasing habit
+An output style quirk is not automatically a subtree.
+
+### 3. A repair preference
+A repair tactic is not the same thing as a structural branch.
+
+### 4. A boundary uncertainty
+If the real issue is still “which family am I in,” the problem is often still boundary-level, not subtree-level.
+
+### 5. A rhetorical category with no stable routing value
+If a label sounds smart but does not improve routing, it has not earned subtree status.
+
+---
+
+## Why subtree expansion matters
+
+Subtrees matter because family-level reading is sometimes too broad for safe or useful next decisions.
+
+A good subtree layer can help with:
+
+- more accurate local routing
+- cleaner fit descriptions
+- lower misrepair risk
+- better explanation of recurring case shapes
+- better public readability between freeze and router
+
+But the subtree layer has to stay disciplined.
+
+Too little subtree work leaves the system vague.  
+Too much subtree work makes the system noisy and unstable.
+
+So the goal is not “more labels.”  
+The goal is “better controlled clarity.”
+
+---
+
+## Public subtree status language
+
+This page uses a simple public status language.
+
+### Stable enough public surface
+A subtree area has enough public structure to be described or linked cleanly without pretending it is frozen core.
+
+### Partially expanded
+A subtree area is clearly present, but public detail is still incomplete.
+
+### Referenced but not public
+A subtree area is conceptually present in the system, but does not yet have a proper public page or stable public naming surface.
+
+### Planned only
+A subtree area is recognized as meaningful for future work, but is not ready to be treated as public structure yet.
+
+### Not yet promoted
+A candidate branch exists in work-thinking or internal shaping, but has not earned public decomposition status.
+
+### Family-level only for now
+The safest public reading remains at family level, because finer splitting would overstate confidence or create false precision.
+
+These status terms help readers understand absence without assuming emptiness.
+
+---
+
+## How to read absent subtree pages
+
+This is important.
+
+If a subtree page does **not** exist yet, that does not automatically mean:
+
+- the pattern is not real
+- the Atlas has no view on it
+- the system is incomplete in a useless way
+
+Sometimes it simply means:
+
+- the public page has not been written yet
+- the naming is not stable enough yet
+- the boundary around that branch is not clean enough yet
+- the branch is still better handled at family level or boundary level
+
+That is why this page exists.
+
+It prevents readers from confusing “not yet public” with “does not exist.”
+
+---
+
+## Current subtree expansion posture by family
+
+This first public version uses a disciplined posture.
+
+It does **not** pretend to publish a full subtree atlas today.  
+Instead, it marks where public subtree work is most meaningful and how that work should be interpreted.
+
+---
+
+## F1 subtree posture
+### Grounding and Evidence Integrity
+
+### Current public posture
+F1 clearly supports subtree work, because grounding failures often differ in meaningful ways at the local routing level.
+
+### Public status
+- stable enough public surface: family layer
+- partially expanded: yes
+- referenced but not public: yes
+- family-level only for some cases: yes
+
+### Why subtree work matters here
+Grounding problems can differ by source quality, anchor mismatch, support drift, and evidence-link failure shape.
+
+Those differences can matter operationally.
+
+### Caution
+Do not mistake every evidence flaw for a stable public subtree.  
+Some F1 cases still belong at family or boundary level first.
+
+---
+
+## F2 subtree posture
+### Reasoning and Progression Integrity
+
+### Current public posture
+F2 also strongly supports subtree work, because reasoning failures often separate meaningfully by progression shape, transition weakness, and inferential instability.
+
+### Public status
+- stable enough public surface: family layer
+- partially expanded: yes
+- referenced but not public: yes
+- family-level only for some cases: yes
+
+### Why subtree work matters here
+Reasoning failures often look similar from far away, but differ greatly when deciding whether the main problem is local jump failure, chain instability, structural omission, or unsound progression.
+
+### Caution
+Do not over-segment purely stylistic reasoning differences into fake subtrees.
+
+---
+
+## F3 subtree posture
+### State and Continuity Integrity
+
+### Current public posture
+F3 supports subtree work in a strong but careful way, because continuity failures often vary across memory carryover, turn linkage, context preservation, and state mutation discipline.
+
+### Public status
+- stable enough public surface: family layer
+- partially expanded: yes
+- referenced but not public: yes
+- family-level only for some cases: yes
+
+### Why subtree work matters here
+Many F3 cases cannot be handled well if they are all treated as one generic continuity failure.
+
+### Caution
+Do not label every long-task degradation as a separate subtree before confirming that continuity is really the right family.
+
+---
+
+## F4 subtree posture
+### Execution and Contract Integrity
+
+### Current public posture
+F4 supports subtree work because execution failures often separate by contract-following shape, tool-action shape, and intent-to-action translation failure.
+
+### Public status
+- stable enough public surface: family layer
+- partially expanded: yes
+- referenced but not public: yes
+- family-level only for some cases: yes
+
+### Why subtree work matters here
+Execution failures often need more than a generic label if later fix direction depends on the exact kind of contract break.
+
+### Caution
+Do not confuse execution subtrees with downstream fix recipes.  
+A fix recipe is not automatically a subtree.
+
+---
+
+## F5 subtree posture
+### Observability and Diagnosability Integrity
+
+### Current public posture
+F5 supports subtree work, but it requires restraint because observability weakness can also block safe subtree separation.
+
+### Public status
+- stable enough public surface: family layer
+- partially expanded: limited
+- referenced but not public: yes
+- family-level only for many cases: yes
+
+### Why subtree work matters here
+Some diagnostic failures differ meaningfully by trace weakness, metric blindness, inspection absence, or instrumentation mismatch.
+
+### Caution
+F5 is one of the easiest places to over-claim structure with too little evidence.  
+Sometimes the right answer is still “visibility too weak to split further.”
+
+---
+
+## F6 subtree posture
+### Boundary and Safety Integrity
+
+### Current public posture
+F6 supports subtree work, especially where different edge-discipline failures have very different consequences.
+
+### Public status
+- stable enough public surface: family layer
+- partially expanded: limited
+- referenced but not public: yes
+- family-level only for many cases: yes
+
+### Why subtree work matters here
+Boundary failures can vary by control breakdown shape, refusal instability, edge-condition weakness, or limit-discipline collapse.
+
+### Caution
+Do not multiply subtrees too fast in safety space.  
+Over-splitting can create more confusion than control.
+
+---
+
+## F7 subtree posture
+### Representation and Localization Integrity
+
+### Current public posture
+F7 supports subtree work, but many cases still need strong discipline because representation failures can be downstream effects of other families.
+
+### Public status
+- stable enough public surface: family layer
+- partially expanded: yes
+- referenced but not public: yes
+- family-level only for some cases: yes
+
+### Why subtree work matters here
+Representation failures can vary across formatting distortion, structural packaging, localization degradation, and output-shape breakdown.
+
+### Caution
+Do not promote a representational branch too quickly if the deeper problem still appears to be F1 or F2.
+
+---
+
+## Public subtree status table 📚
+
+| Family | Public family layer | Partial subtree expansion | Referenced but not public | Family-level only still common | Main caution |
+|---|---|---|---|---|---|
+| F1 | Yes | Yes | Yes | Yes | do not confuse evidence flaws with arbitrary branch labels |
+| F2 | Yes | Yes | Yes | Yes | do not over-segment stylistic reasoning differences |
+| F3 | Yes | Yes | Yes | Yes | confirm continuity is really the primary family first |
+| F4 | Yes | Yes | Yes | Yes | do not confuse contract subtrees with fix recipes |
+| F5 | Yes | Limited | Yes | Yes | weak visibility often blocks safe subtree splitting |
+| F6 | Yes | Limited | Yes | Yes | safety-space over-splitting can reduce control clarity |
+| F7 | Yes | Yes | Yes | Yes | representation may be downstream of deeper families |
+
+---
+
+## Subtree expansion rules
+
+A public subtree should generally be expanded only when it improves one or more of the following:
+
+### 1. Routing clarity
+The subtree helps separate meaningful cases more cleanly than staying vague.
+
+### 2. Boundary safety
+The subtree reduces confusion with nearby families or nearby branches.
+
+### 3. Fit usefulness
+The subtree improves later fit description or confidence discipline.
+
+### 4. Repair safety
+The subtree helps prevent misrepair or bad first moves.
+
+### 5. Public readability
+The subtree makes the Atlas easier to study without turning it into noise.
+
+If these gains are not visible, the branch may not yet deserve public expansion.
+
+---
+
+## Subtree restraint rules
+
+A subtree should **not** be promoted too fast just because:
+
+- it sounds smart
+- it feels more detailed
+- it resembles a one-off example
+- it makes a chart look fuller
+- it allows rhetorical inflation
+
+Subtree work should stay tied to routing usefulness.
+
+This is one of the most important discipline rules in the Atlas middle layer.
+
+---
+
+## Common subtree mistakes
+
+### Mistake 1. Treating every recurring pattern as a subtree
+Not every recurrence deserves its own branch.
+
+### Mistake 2. Skipping the boundary layer
+If the family boundary is still unclear, subtree work is often premature.
+
+### Mistake 3. Confusing subtree with overlay
+A mixed case is not automatically a subtree.
+
+### Mistake 4. Confusing subtree with repair tactic
+A repair move can be important without defining a structural branch.
+
+### Mistake 5. Treating “not yet public” as “not real”
+Public absence is not the same thing as structural emptiness.
+
+---
+
+## When this page is enough
+
+This page is often enough when:
+
+- you want to understand how subtree work is managed
+- you want to know whether a finer branch is already public
+- you want to explain why a case should remain at family or boundary level for now
+- you want a public status language for subtree visibility
+
+In those situations, this page does its job.
+
+---
+
+## When this page is not enough
+
+This page is usually not enough when:
+
+- you need a confident fit judgment
+- you need first-fix direction
+- you need overlay handling
+- you need output contract discipline
+- you need a specific repair-facing action path
+
+Then the right next pages are:
+
+- [Atlas Fit Candidate Registry v1](./atlas-fit-candidate-registry-v1.md)
+- [Atlas First Fix and Misrepair Discipline v1](./atlas-first-fix-and-misrepair-discipline-v1.md)
+- [Atlas Evidence and Confidence Discipline v1](./atlas-evidence-and-confidence-discipline-v1.md)
+
+---
+
+## Practical use
+
+Here is the simplest practical workflow.
+
+### Step 1
+Start with:
+- [Atlas Family Mini-Specs](./atlas-family-mini-specs-v1.md)
+
+### Step 2
+If needed, clarify the main neighboring family boundary:
+- [Atlas Boundary Decision Guide](./atlas-boundary-decision-guide-v1.md)
+
+### Step 3
+Ask whether a finer local branch is really needed.
+
+### Step 4
+Use this page to decide whether the area is:
+- stable enough public surface
+- partially expanded
+- referenced but not public
+- planned only
+- family-level only for now
+
+### Step 5
+Only then move to fit or repair discipline.
+
+This sequence keeps subtree work useful instead of noisy.
+
+---
+
+## Relation to other Atlas docs
+
+This page sits after family and boundary, but before fit and repair discipline.
+
+### Upstream neighbors
+These pages prepare the reader for subtree work:
+- [Problem Map 3.0 Troubleshooting Atlas](../wfgy-ai-problem-map-troubleshooting-atlas.md)
+- [Atlas Structure Map](./atlas-structure-map-v1.md)
+- [Atlas Family Mini-Specs](./atlas-family-mini-specs-v1.md)
+- [Atlas Boundary Decision Guide](./atlas-boundary-decision-guide-v1.md)
+
+### Side neighbor
+This page pairs especially well with:
+- [Canonical Casebook v1](./canonical-casebook-v1.md)
+
+Why:
+the casebook shows example-shaped use, while this page controls the visibility and status language of subtree expansion.
+
+### Downstream neighbors
+These are the natural next pages:
+- [Atlas Fit Candidate Registry v1](./atlas-fit-candidate-registry-v1.md)
+- [Atlas First Fix and Misrepair Discipline v1](./atlas-first-fix-and-misrepair-discipline-v1.md)
+- [Atlas Evidence and Confidence Discipline v1](./atlas-evidence-and-confidence-discipline-v1.md)
+
+Why:
+this page explains how subtree expansion is organized, but later pages govern how detailed classification and action should be handled safely.
+
+---
+
+## Current status
+
+This page should be read as the stable **public subtree control page**.
+
+That means:
+
+- it does not pretend all subtrees are already written
+- it does not silently rewrite the frozen core
+- it gives readers a clean way to understand subtree visibility
+- it makes public expansion more legible and less ad hoc
+
+Its main value is governance-through-clarity.
+
+It helps people know when subtree work is real, when it is partial, and when it should wait.
+
+---
+
+## Future extension
+
+This page will become more powerful as the Atlas middle layer grows.
+
+The most important future companions are:
+
+- [Atlas Fit Candidate Registry v1](./atlas-fit-candidate-registry-v1.md)
+- [Atlas First Fix and Misrepair Discipline v1](./atlas-first-fix-and-misrepair-discipline-v1.md)
+- [Atlas Promotion and Patch Thresholds v1](./atlas-promotion-and-patch-thresholds-v1.md)
+
+Later versions may also attach explicit public subtree pages under specific families.
+
+But even then, this page should remain the index and status-control surface.
+
+That role should stay stable.
+
+---
+
+## Closing note 🔭
+
+A strong system does not only know how to classify.
+
+It also knows how to grow its own detail without becoming chaotic.
+
+That is what subtree discipline is for.
+
+This page makes that discipline public.
+
+It tells readers:
+
+where the Atlas is already fine-grained enough,  
+where it is only partly expanded,  
+where it is still open,  
+and where staying at family level is still the safer and more honest move.