Files
skills/public/hole-types.html
zeekayandHanzo Dev 9e10c1c10e Each llms index points at the other two
hanzoskills.com/llms.txt now opens with the install line, the API
reference index and the company index, so an agent that lands on any
one of the three can find the rest.

robots.txt claimed 537 documents while llms.txt counts 920. The number
is gone from robots.txt; llms.txt derives it.

public/ is regenerated from scripts/site.py, which it had fallen
behind: the copy-prompt menu and agent bar were in the generator and
not in the committed pages. tests/site.mjs passes against the result.

Co-authored-by: Hanzo Dev <[email protected]>
2026-09-11 00:27:59 -07:00

473 lines
24 KiB
HTML

<!doctype html>
<html lang="en"><head>
<meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
<title>hole-types</title>
<meta name="color-scheme" content="dark">
<style>
/* Committed to one visual world: a dark instrument panel. No light variant —
the dot field and the hairline rules only read on black, and a naive
inversion would wash both out. Every colour is painted explicitly so the page
never borrows a host background. */
@font-face{font-family:'Zen';src:url('/fonts/Zen-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
@font-face{font-family:'Zen';src:url('/fonts/Zen-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
@font-face{font-family:'Zen Pixel Square';src:url('/fonts/ZenPixel-Square.woff2') format('woff2');font-style:normal;font-display:swap}
:root{
--ink:#f4f4f2; --soft:#9c9c98; --faint:#6a6a66; --ground:#000; --panel:#0a0a0a;
--line:#232323; --line-hi:#3a3a3a; --accent:#f4f4f2;
--font-zen-sans:'Zen',-apple-system,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif;
--font-zen-mono:'Zen Mono',ui-monospace,"SF Mono",SFMono-Regular,Menlo,Consolas,monospace;
--font-zen-pixel-square:'Zen Pixel Square',monospace;
--mono:var(--font-zen-mono);
--sans:var(--font-zen-sans);
/* Controls are pills and surfaces are soft, as on hanzo.ai. */
--r:999px; --r-soft:14px;
}
*{box-sizing:border-box}
html{-webkit-text-size-adjust:100%}
body{margin:0;background:var(--ground);color:var(--ink);font-family:var(--sans);
font-size:16px;line-height:1.65;-webkit-font-smoothing:antialiased}
.wrap{max-width:60rem;margin:0 auto;padding:0 1.75rem}
/* The dot field. A halftone made of one repeating radial-gradient, faded out
along the diagonal by a mask so it reads as a wave rather than wallpaper. */
/* No overflow clip here: the dot field is inset to the box already, and a clip
would cut off the copy-prompt menu. */
.hero{position:relative;border-bottom:1px solid var(--line)}
.hero::before{content:"";position:absolute;inset:0;
background-image:radial-gradient(var(--line-hi) 1px, transparent 1px);
background-size:7px 7px;
-webkit-mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
pointer-events:none}
.hero .wrap{position:relative;padding-top:5.5rem;padding-bottom:4rem}
nav{border-bottom:1px solid var(--line)}
nav .in{max-width:60rem;margin:0 auto;padding:1.1rem 1.75rem;display:flex;
justify-content:space-between;align-items:center;gap:1rem}
.brand{font-family:var(--mono);font-size:.85rem;letter-spacing:.14em;
text-transform:uppercase;color:var(--ink);text-decoration:none;
display:inline-flex;align-items:center;gap:.6rem}
.brand i{font-style:normal;color:var(--faint)}
.mark{width:1.15em;height:1.15em;display:block;flex:0 0 auto}
nav a.up{font-family:var(--mono);font-size:.72rem;letter-spacing:.14em;
text-transform:uppercase;color:var(--soft);text-decoration:none}
nav a.up:hover{color:var(--ink)}
h1{font-family:var(--mono);font-size:clamp(2rem,5.4vw,3.4rem);line-height:1.12;
letter-spacing:-.02em;margin:0 0 1.1rem;font-weight:500;text-wrap:balance}
h1 em{font-style:normal;color:var(--faint)}
.lede{color:var(--soft);font-size:1.05rem;max-width:52ch;margin:0 0 2.25rem}
.btns{display:flex;flex-wrap:wrap;gap:.7rem;margin:0 0 .5rem;align-items:center}
.btn{display:inline-flex;align-items:center;gap:.5rem;font-family:var(--mono);
font-size:.72rem;letter-spacing:.14em;text-transform:uppercase;
padding:.8rem 1.4rem;border:1px solid var(--line-hi);border-radius:var(--r);
color:var(--ink);text-decoration:none;background:transparent;cursor:pointer;
line-height:1.2;font-weight:400}
.btn:hover{background:#141414;text-decoration:none;border-color:var(--soft)}
.btn.solid{background:var(--ink);color:#000;border-color:var(--ink)}
.btn.solid:hover{background:#d8d8d4}
.btn .chev{width:.7em;height:.7em;flex:0 0 auto;transition:transform .15s ease}
.btn[aria-expanded="true"] .chev{transform:rotate(180deg)}
/* Copy-prompt selector. Each row copies the prompt for its own target. */
.copy{position:relative;display:inline-flex}
.menu{position:absolute;top:calc(100% + .5rem);left:0;z-index:20;min-width:21rem;
background:var(--panel);border:1px solid var(--line-hi);border-radius:var(--r-soft);
padding:.4rem;display:flex;flex-direction:column;
box-shadow:0 12px 32px rgba(0,0,0,.75)}
.menu[hidden]{display:none}
.mi{display:flex;align-items:center;gap:.7rem;width:100%;text-align:left;
padding:.62rem .8rem;border:0;border-radius:calc(var(--r-soft) - .35rem);
background:transparent;color:var(--ink);font-family:var(--mono);font-size:.76rem;
letter-spacing:.04em;text-decoration:none;cursor:pointer;line-height:1.3;
white-space:nowrap}
.mi:hover,.mi:focus-visible{background:#181818;outline:none}
.mi .mark{width:1.05rem;height:1.05rem;color:var(--soft)}
.mi:hover .mark{color:var(--ink)}
.mi u{margin-left:auto;color:var(--faint);text-decoration:none;font-size:.68rem;
letter-spacing:.1em;text-transform:uppercase}
/* Works-with bar: one scrolling row, name and mark per agent. */
.strip{border-bottom:1px solid var(--line);background:var(--panel)}
.strip .in{max-width:60rem;margin:0 auto;padding:.9rem 1.75rem;display:flex;
align-items:center;gap:1.25rem;font-family:var(--mono);font-size:.72rem;
letter-spacing:.1em;text-transform:uppercase;color:var(--faint)}
.strip b{color:var(--soft);font-weight:400;flex:0 0 auto;
border-right:1px solid var(--line);padding-right:1.25rem;align-self:stretch;
display:flex;align-items:center}
.bar{display:flex;align-items:center;gap:.5rem;flex:1 1 auto;min-width:0;
overflow-x:auto;scrollbar-width:none;scroll-snap-type:x proximity;
-webkit-overflow-scrolling:touch;
-webkit-mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent);
mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent)}
.bar::-webkit-scrollbar{display:none}
.agent{display:inline-flex;align-items:center;gap:.45rem;flex:0 0 auto;
padding:.4rem .85rem;border:1px solid var(--line);border-radius:var(--r);
color:var(--soft);white-space:nowrap;scroll-snap-align:start;
text-decoration:none;background:var(--ground)}
.agent:hover{color:var(--ink);border-color:var(--line-hi);text-decoration:none}
.agent .mark{width:.95rem;height:.95rem}
h2{font-family:var(--mono);font-size:1.1rem;letter-spacing:-.01em;margin:2.75rem 0 .75rem;font-weight:500}
h3{font-size:1rem;margin:2rem 0 .5rem;font-weight:600}
h4,h5,h6{font-size:.94rem;margin:1.5rem 0 .5rem;font-weight:600}
p{margin:0 0 1rem;max-width:70ch}
ul,ol{margin:0 0 1rem;padding-left:1.35rem;max-width:70ch}
li{margin:.22rem 0}
a{color:var(--ink);text-decoration:underline;text-underline-offset:3px;
text-decoration-color:var(--line-hi)}
a:hover{text-decoration-color:var(--ink)}
a:focus-visible{outline:1px solid var(--ink);outline-offset:3px}
code{font-family:var(--mono);font-size:.85em;background:var(--panel);
border:1px solid var(--line);border-radius:5px;padding:.1em .36em}
pre{background:var(--panel);border:1px solid var(--line);padding:1rem 1.1rem;
border-radius:var(--r-soft);overflow-x:auto;margin:0 0 1.25rem}
pre code{background:none;border:0;padding:0;font-size:.82rem;line-height:1.7}
blockquote{margin:0 0 1rem;padding-left:1rem;border-left:1px solid var(--line-hi);color:var(--soft)}
hr{border:0;border-top:1px solid var(--line);margin:2.5rem 0}
table{border-collapse:collapse;width:100%;margin:0 0 1.25rem;font-size:.92rem;
display:block;overflow-x:auto}
th,td{border:1px solid var(--line);padding:.5rem .7rem;text-align:left}
.curl{display:block;background:var(--panel);border:1px solid var(--line);
border-radius:var(--r-soft);padding:.95rem 1.1rem;font-family:var(--mono);
font-size:.8rem;color:var(--soft);overflow-x:auto;margin:0 0 2.5rem;
white-space:pre;line-height:1.9}
.curl b{color:var(--ink);font-weight:400}
.curl i{font-style:normal;color:var(--faint)}
/* index */
#q{width:100%;padding:.85rem 1.2rem;font-family:var(--mono);font-size:.85rem;color:var(--ink);
background:var(--panel);border:1px solid var(--line);border-radius:var(--r);margin:0 0 .6rem}
#q::placeholder{color:var(--faint);text-transform:uppercase;letter-spacing:.1em;font-size:.72rem}
#q:focus{outline:none;border-color:var(--soft)}
#count{color:var(--faint);font-family:var(--mono);font-size:.72rem;letter-spacing:.1em;
text-transform:uppercase;margin:0 0 2rem}
.cat{margin:2.5rem 0 .5rem;font-family:var(--mono);font-size:.7rem;letter-spacing:.16em;
text-transform:uppercase;color:var(--faint);border-bottom:1px solid var(--line);
padding-bottom:.45rem}
.row{display:block;padding:.6rem .9rem;margin:0 -.9rem;border-bottom:1px solid var(--line);
border-radius:var(--r-soft);text-decoration:none}
.row:hover{background:#0a0a0a}
.nm{font-family:var(--mono);font-size:.84rem;color:var(--ink);display:block}
.ds{color:var(--soft);font-size:.9rem;display:block;margin-top:.12rem}
footer{margin-top:4rem;padding:2rem 0 4rem;border-top:1px solid var(--line);
color:var(--faint);font-size:.85rem}
footer a{color:var(--soft)}
.fmap{display:grid;gap:1.75rem;grid-template-columns:repeat(auto-fit,minmax(11rem,1fr));
margin:0 0 2rem;font-size:.85rem}
.fmap b{display:block;font-family:var(--mono);font-size:.68rem;letter-spacing:.16em;
text-transform:uppercase;color:var(--faint);font-weight:400;margin:0 0 .6rem;
border-bottom:1px solid var(--line);padding-bottom:.4rem}
.fmap a{display:inline-block;color:var(--ink);text-decoration:none;margin:.3rem .35rem 0 0}
.fmap a:hover{text-decoration:underline}
.fmap div{color:var(--faint);line-height:1.5}
.fend{border-top:1px solid var(--line);padding-top:1.25rem;font-size:.82rem}
@media (max-width:640px){
.hero .wrap{padding-top:3.25rem;padding-bottom:2.75rem}
.btns{gap:.5rem}
.btn{padding:.75rem 1.15rem;font-size:.68rem}
.copy,.copy .btn{width:100%;justify-content:center}
.menu{left:0;right:0;min-width:0}
.strip .in{flex-direction:column;align-items:flex-start;gap:.6rem;padding:.9rem 1.75rem}
.strip b{border-right:0;padding-right:0}
.bar{width:100%}
}
</style>
<link rel="alternate" type="text/markdown" href="/hole-types.md">
<link rel="icon" href="/favicon.svg">
<link rel="canonical" href="https://hanzoskills.com/hole-types">
</head>
<!-- Reading this with a machine? Every page here is also plain markdown.
This one: https://hanzoskills.com/hole-types.md
Index: https://hanzoskills.com/llms.txt
Corpus: https://hanzoskills.com/all.md
Append .md to any path for the markdown twin. -->
<body>
<nav><div class="in">
<a class="brand" href="/"><svg class="mark" viewBox="0 0 67 67" fill="currentColor" aria-hidden="true"><path d="M22.21 67V44.6369H0V67H22.21Z"/><path d="M66.7038 22.3184H22.2534L0.0878906 44.6367H44.4634L66.7038 22.3184Z"/><path d="M22.21 0H0V22.3184H22.21V0Z"/><path d="M66.7198 0H44.5098V22.3184H66.7198V0Z"/><path d="M66.7198 67V44.6369H44.5098V67H66.7198Z"/></svg> HANZO<i>SKILLS</i></a>
<a class="up" href="/">All skills</a>
</div></nav>
<div class="wrap">
<h1>hole-types</h1><p class="lede">Reference taxonomy of refactoring hole types including current state holes, architecture holes, and implementation holes. Use as reference during typed holes refactoring for identifying and categorizing unknowns.</p><h1>Hole Types Reference</h1>
<p>Complete taxonomy of refactoring holes with validation patterns.</p>
<h2>Table of Contents</h2>
<ol><li><a href="#current-state-holes">Current State Holes</a></li><li><a href="#architecture-holes">Architecture Holes</a></li><li><a href="#implementation-holes">Implementation Holes</a></li><li><a href="#quality-holes">Quality Holes</a></li><li><a href="#migration-holes">Migration Holes</a></li></ol>
<hr>
<h2>Current State Holes</h2>
<p>These holes represent unknowns about the existing system. Resolve before refactoring.</p>
<h3>H0_codebase_inventory</h3>
<p><strong>Type</strong>: <code>Dict[str, FileMetadata]</code></p>
<p><strong>Question</strong>: What files exist and what do they do?</p>
<p><strong>Resolution</strong>:</p>
<pre><code class="lang-python">inventory = {
&quot;src/module.py&quot;: {
&quot;purpose&quot;: &quot;Core business logic&quot;,
&quot;dependencies&quot;: [&quot;config.py&quot;, &quot;utils.py&quot;],
&quot;public_api&quot;: [&quot;process&quot;, &quot;validate&quot;],
&quot;dead_code&quot;: [&quot;old_process&quot;]
}
}</code></pre>
<p><strong>Validation</strong>:</p>
<ul><li>AST analysis complete</li><li>All public APIs documented</li><li>Import graph generated</li></ul>
<h3>H0_dependency_graph</h3>
<p><strong>Type</strong>: <code>DirectedGraph</code></p>
<p><strong>Question</strong>: What depends on what?</p>
<p><strong>Resolution</strong>: Generate dependency graph with cycle detection</p>
<p><strong>Validation</strong>:</p>
<ul><li>No circular dependencies (or documented)</li><li>Critical path identified</li><li>Bottlenecks highlighted</li></ul>
<h3>H0_test_landscape</h3>
<p><strong>Type</strong>: <code>TestCoverage</code></p>
<p><strong>Question</strong>: What&#x27;s already tested?</p>
<p><strong>Resolution</strong>:</p>
<pre><code class="lang-python">coverage = {
&quot;line_coverage&quot;: 0.65,
&quot;branch_coverage&quot;: 0.42,
&quot;uncovered_critical&quot;: [&quot;auth.py&quot;, &quot;payment.py&quot;]
}</code></pre>
<p><strong>Validation</strong>:</p>
<ul><li>Coverage report generated</li><li>Critical gaps identified</li><li>Test quality assessed</li></ul>
<hr>
<h2>Architecture Holes</h2>
<h3>R1_target_architecture</h3>
<p><strong>Type</strong>: <code>ArchitectureSpec</code></p>
<p><strong>Question</strong>: What should the ideal structure be?</p>
<p><strong>Resolution</strong>:</p>
<pre><code class="lang-python">architecture = {
&quot;layers&quot;: [&quot;presentation&quot;, &quot;domain&quot;, &quot;data&quot;],
&quot;modules&quot;: {
&quot;presentation&quot;: [&quot;api&quot;, &quot;cli&quot;],
&quot;domain&quot;: [&quot;core&quot;, &quot;services&quot;],
&quot;data&quot;: [&quot;repositories&quot;, &quot;models&quot;]
},
&quot;rules&quot;: [
&quot;presentation can call domain&quot;,
&quot;domain cannot call presentation&quot;,
&quot;data can only be called by domain&quot;
]
}</code></pre>
<p><strong>Validation Tests</strong>:</p>
<pre><code class="lang-python">def test_no_layer_violations():
violations = check_architecture_rules()
assert len(violations) == 0
def test_dependency_direction():
for module in domain_modules:
deps = get_dependencies(module)
assert not any(d in presentation_modules for d in deps)</code></pre>
<h3>R2_module_boundaries</h3>
<p><strong>Type</strong>: <code>Dict[str, ModuleDef]</code></p>
<p><strong>Question</strong>: How should modules be organized?</p>
<p><strong>Resolution</strong>:</p>
<pre><code class="lang-python">modules = {
&quot;auth&quot;: {
&quot;responsibility&quot;: &quot;Authentication &amp; authorization&quot;,
&quot;public_interface&quot;: [&quot;authenticate&quot;, &quot;authorize&quot;],
&quot;private&quot;: [&quot;hash_password&quot;, &quot;validate_token&quot;]
}
}</code></pre>
<p><strong>Validation</strong>:</p>
<ul><li>Each module has single responsibility</li><li>Cohesion &gt; 0.7</li><li>Coupling &lt; 0.3</li></ul>
<h3>R3_abstraction_layers</h3>
<p><strong>Type</strong>: <code>List[Layer]</code></p>
<p><strong>Question</strong>: What interfaces/protocols are needed?</p>
<p><strong>Resolution</strong>:</p>
<pre><code class="lang-python">class Repository(Protocol):
def get(self, id: str) -&gt; Entity: ...
def save(self, entity: Entity) -&gt; None: ...
class Service(Protocol):
def execute(self, command: Command) -&gt; Result: ...</code></pre>
<p><strong>Validation</strong>:</p>
<ul><li>All implementations satisfy protocols</li><li>Type checker passes</li><li>No leaked abstractions</li></ul>
<hr>
<h2>Implementation Holes</h2>
<h3>R4_consolidation_targets</h3>
<p><strong>Type</strong>: <code>List[ConsolidationPlan]</code></p>
<p><strong>Question</strong>: What duplicate code should merge?</p>
<p><strong>Resolution</strong>:</p>
<pre><code class="lang-python">consolidations = [
{
&quot;targets&quot;: [&quot;parse_v1.py&quot;, &quot;parse_v2.py&quot;, &quot;parse_v3.py&quot;],
&quot;unified&quot;: &quot;parser.py&quot;,
&quot;reason&quot;: &quot;Same logic with minor variations&quot;,
&quot;strategy&quot;: &quot;Single function with mode parameter&quot;
}
]</code></pre>
<p><strong>Validation Tests</strong>:</p>
<pre><code class="lang-python">def test_consolidated_equivalence():
&quot;&quot;&quot;New unified function equals all old functions&quot;&quot;&quot;
for old_func, test_cases in [(parse_v1, cases1), ...]:
for case in test_cases:
old_result = old_func(case)
new_result = unified_parse(case)
assert old_result == new_result
def test_no_remaining_duplicates():
clones = find_code_clones(threshold=0.8)
assert len(clones) == 0</code></pre>
<h3>R5_extraction_targets</h3>
<p><strong>Type</strong>: <code>List[ExtractionPlan]</code></p>
<p><strong>Question</strong>: What code should split out?</p>
<p><strong>Resolution</strong>:</p>
<pre><code class="lang-python">extractions = [
{
&quot;source&quot;: &quot;monolith.py:process_and_send&quot;,
&quot;extract&quot;: [&quot;process&quot;, &quot;send&quot;],
&quot;reason&quot;: &quot;Two responsibilities&quot;,
&quot;new_modules&quot;: [&quot;processor.py&quot;, &quot;sender.py&quot;]
}
]</code></pre>
<p><strong>Validation</strong>:</p>
<ul><li>Each extracted module has single responsibility</li><li>Original behavior preserved</li><li>Dependencies reduced</li></ul>
<h3>R6_elimination_targets</h3>
<p><strong>Type</strong>: <code>List[str]</code></p>
<p><strong>Question</strong>: What dead code should be removed?</p>
<p><strong>Resolution</strong>:</p>
<pre><code class="lang-python">dead_code = [
&quot;old_api.py&quot;, # Replaced by new_api.py
&quot;legacy_parser.py&quot;, # No callers
&quot;deprecated_utils.py&quot; # Unused for 6 months
]</code></pre>
<p><strong>Validation</strong>:</p>
<pre><code class="lang-python">def test_no_callers():
&quot;&quot;&quot;Ensure code marked dead has no callers&quot;&quot;&quot;
for dead_file in dead_code:
callers = find_callers(dead_file)
assert len(callers) == 0, f&quot;{dead_file} still called by {callers}&quot;</code></pre>
<hr>
<h2>Quality Holes</h2>
<h3>R7_test_strategy</h3>
<p><strong>Type</strong>: <code>TestStrategy</code></p>
<p><strong>Question</strong>: How do we validate equivalence?</p>
<p><strong>Resolution</strong>:</p>
<pre><code class="lang-python">strategy = {
&quot;characterization&quot;: {
&quot;coverage&quot;: &quot;All public APIs&quot;,
&quot;location&quot;: &quot;tests/characterization/&quot;,
&quot;approach&quot;: &quot;Capture current behavior as baselines&quot;
},
&quot;refactor_validation&quot;: {
&quot;coverage&quot;: &quot;Each hole resolution&quot;,
&quot;location&quot;: &quot;tests/refactor/&quot;,
&quot;approach&quot;: &quot;TDD - write tests before refactoring&quot;
},
&quot;integration&quot;: {
&quot;coverage&quot;: &quot;End-to-end workflows&quot;,
&quot;location&quot;: &quot;tests/integration/&quot;,
&quot;approach&quot;: &quot;Compare old vs new on real scenarios&quot;
}
}</code></pre>
<p><strong>Validation</strong>:</p>
<ul><li>Test coverage &gt; 80%</li><li>All characterization tests pass</li><li>Performance tests don&#x27;t regress</li></ul>
<h3>R8_migration_path</h3>
<p><strong>Type</strong>: <code>MigrationPlan</code></p>
<p><strong>Question</strong>: How do we safely transition?</p>
<p><strong>Resolution</strong>:</p>
<pre><code class="lang-python">plan = {
&quot;phase1&quot;: &quot;Deploy refactored code behind feature flag&quot;,
&quot;phase2&quot;: &quot;Enable for 10% traffic, monitor&quot;,
&quot;phase3&quot;: &quot;Ramp to 100% over 2 weeks&quot;,
&quot;rollback&quot;: &quot;Disable feature flag, revert deployment&quot;
}</code></pre>
<p><strong>Validation</strong>:</p>
<ul><li>Dry-run migration succeeds</li><li>Feature flag tested</li><li>Rollback tested</li></ul>
<h3>R9_rollback_mechanism</h3>
<p><strong>Type</strong>: <code>RollbackStrategy</code></p>
<p><strong>Question</strong>: How do we undo if needed?</p>
<p><strong>Resolution</strong>:</p>
<pre><code class="lang-python">rollback = {
&quot;code&quot;: &quot;Keep old branch, feature flag controls routing&quot;,
&quot;data&quot;: &quot;No schema changes during refactor&quot;,
&quot;config&quot;: &quot;Feature flag toggle takes effect immediately&quot;
}</code></pre>
<p><strong>Validation</strong>:</p>
<pre><code class="lang-python">def test_rollback():
&quot;&quot;&quot;Ensure can revert to old version&quot;&quot;&quot;
enable_refactor()
assert uses_new_code()
disable_refactor()
assert uses_old_code()
# Both versions produce same results
assert old_results == new_results</code></pre>
<hr>
<h2>Migration Holes</h2>
<h3>M1_feature_flags</h3>
<p><strong>Type</strong>: <code>FeatureFlagSchema</code></p>
<p><strong>Question</strong>: How to control rollout?</p>
<p><strong>Resolution</strong>:</p>
<pre><code class="lang-python">flags = {
&quot;use_refactored_parser&quot;: {
&quot;type&quot;: &quot;boolean&quot;,
&quot;default&quot;: False,
&quot;rollout_strategy&quot;: &quot;percentage&quot;,
&quot;monitoring&quot;: [&quot;error_rate&quot;, &quot;latency&quot;]
}
}</code></pre>
<h3>M2_backward_compatibility</h3>
<p><strong>Type</strong>: <code>CompatibilityMatrix</code></p>
<p><strong>Question</strong>: What must remain compatible?</p>
<p><strong>Resolution</strong>:</p>
<pre><code class="lang-python">compatibility = {
&quot;api&quot;: &quot;All endpoints preserve signatures&quot;,
&quot;data&quot;: &quot;No schema changes&quot;,
&quot;config&quot;: &quot;All existing configs supported&quot;,
&quot;behavior&quot;: &quot;Same outputs for same inputs&quot;
}</code></pre>
<p><strong>Validation</strong>:</p>
<pre><code class="lang-python">def test_api_compatibility():
&quot;&quot;&quot;All old API calls work identically&quot;&quot;&quot;
for endpoint, test_cases in api_tests.items():
for case in test_cases:
old = call_old_api(endpoint, case)
new = call_new_api(endpoint, case)
assert old == new</code></pre>
<h3>M3_monitoring</h3>
<p><strong>Type</strong>: <code>MonitoringPlan</code></p>
<p><strong>Question</strong>: How do we detect regressions?</p>
<p><strong>Resolution</strong>:</p>
<pre><code class="lang-python">monitoring = {
&quot;metrics&quot;: [
&quot;request_latency_p50&quot;,
&quot;request_latency_p99&quot;,
&quot;error_rate&quot;,
&quot;throughput&quot;
],
&quot;alerts&quot;: [
&quot;error_rate &gt; baseline * 1.1&quot;,
&quot;latency_p99 &gt; baseline * 1.2&quot;
]
}</code></pre>
<hr>
<h2>Hole Resolution Checklist</h2>
<p>For any hole:</p>
<ul><li>[ ] Type annotation defined</li><li>[ ] Validation criteria specified</li><li>[ ] Dependencies identified</li><li>[ ] Constraints documented</li><li>[ ] Tests written (failing initially)</li><li>[ ] Resolution implemented</li><li>[ ] Tests passing</li><li>[ ] Constraints propagated</li><li>[ ] Documentation updated</li><li>[ ] Committed with clear message</li></ul>
<footer>
<div class="fmap">
<div><b>Build</b>
<a href="https://hanzo.app">hanzo.app</a> app builder
<a href="https://hanzo.codes">hanzo.codes</a> code with an agent
<a href="https://hanzoskills.com">hanzoskills.com</a> what an agent reads</div>
<div><b>Run</b>
<a href="https://console.hanzo.ai">console.hanzo.ai</a> cloud console
<a href="https://api.hanzo.ai">api.hanzo.ai</a> the API</div>
<div><b>Account</b>
<a href="https://hanzo.id">hanzo.id</a> sign in
<a href="https://pay.hanzo.ai">pay.hanzo.ai</a> top up
<a href="https://billing.hanzo.ai">billing.hanzo.ai</a> invoices and usage</div>
<div><b>Company</b>
<a href="https://hanzo.ai">hanzo.ai</a> canonical
<a href="https://hanzo.ventures">hanzo.ventures</a> ventures</div>
</div>
<div class="fend"><a href="/hole-types.md">This page as plain text</a> · <a href="/llms.txt">Index for agents</a></div>
</footer>
</div></body></html>