{"slug": "linear-margin-note-methodology-skill", "title": "Linear Margin-Note Methodology Skill", "summary": "A developer introduced a linear margin-note methodology for distilling technical papers, algorithms, and codebases into append-only reasoning layers. The approach structures analysis into ordered files covering concept inventory, dependency graphs, glossaries, and code alignment, aiming to reduce context drift in language models and support architectural refactoring. It emphasizes source citations, cross-checks, and showstopper gates to ensure correctness.", "body_md": "| name | linear-margin-note-methodology |\n|---|---|\n| description | Use when distilling a technical paper, specification, algorithm, or codebase into append-only margin notes, a dependency-ordered ontology, a glossary, reviewed design documentation, and code-alignment findings. |\n\nTurn a dense technical source into a sequence of inspectable, append-only reasoning layers. Each layer moves forward from source detail toward a corrected ontology, dependency order, synthesis, documentation, and code review without rewriting the evidence produced by earlier passes. The final layer is to be a standalone detailed technical explaination of the concepts as structured prose that is pedagogically optimised that is of sufficent quality to be a primer to the topic.\n\nAutoregressive language models benefit from this externalized linear process because each pass has a narrower task, stable prior artifacts, and explicit terminology. That reduces ambiguity and context drift. It does not make a model correct: source citations, independent cross-checks, and showstopper gates remain mandatory.\n\nThis technique is suited to technical papers, mathematical algorithms, mechanics, protocols, and codebases where concepts have real dependencies and conversational summarization would hide them. It is also suitable run at an architectual refactoring phase where the code itself, the doc-comments of the code, and the design documentation, and prior runs are the input. That allows for an architectual refactor phase were architectual weeds can be removed and long-term drift removed from the codebase through periodical realignmet. It may be the case that the drift is the correct new path and the original design is out of date with the latest competative landscape. The \"Andon アンドン\" concept below should be seen as the highest level of mastery that the very foundational assumptions may be challenged and changed at any time.\n\n- Work inside a fresh project-local scratch directory, never an operating-system temporary path.\n- Write each layer forward and append-only. Do not repair an earlier layer after learning more; create the next corrective layer so comparisons remain possible.\n- Cover every substantive source paragraph, sentence, protocol step, equation, diagram claim, or code symbol. Record source locations.\n- Give each concept one qualified, unambiguous preferred name. Detect collisions and aliases.\n- Add a glossary term on first encounter only. Never duplicate definitions.\n- Discover, categorize and separate concepts such as correctness/safety requirements from liveness assumptions, yet also consider what might be optimizations, pragmatics, scope, historical explanation, and implementation choices.\n- State why each idea exists. A protocol step without its reason cannot be reviewed intelligently.\n- Do not synthesize final prose until the concept inventory, dependency graph, and source cross-check exist.\n- Apply Andon アンドン to avoid any possible future product recall: the aim is to create a formal definition from which a real system can be built. It is an unlimited liablity future risk and so a showstopper if the formalism is internally inconsistent, has undocumented undefined behaviours, or else permits arbitrary parallel architectures to coexist.\n- Keep old mistakes out of the final layer documentation. History remains visible in scratch layers; final docs contain only the corrected model and an explicit terminology mapping where needed.\n\nUse ordered files so each pass is independently readable:\n\n```\n.tmp/-review/\n source-01-
.md\n source-02-
.md\n ...\n concept-inventory.md\n concept-dependencies.md\n dependency-depth-order.md\n corrected-formalism.md\n glossary.md\n crosscheck-source-formalism.md\n docs-review.md\n code-01-.md\n code-02-.md\n ...\n code-hardening-delta.md\n```\n\nParallel agents may write non-overlapping files. Only one pass may append glossary entries after deduplicating candidates from all parallel layers. Passes before that are aligned to elaboration, discovery and enumeration. Passes after that are conslidation and refinement. This means that the writing of the glossary is a critical disambiguation fulcrum point. While Andon アンドン may be called at any phase the point of the writing of the glossary is where the most value and least cost is to ask and where discussion and knowledge-transfer bloom from false positivies. Stopping the line here is to be celebrated. In particular if the new glossary differs significantly from prior runs or any pre-existing code or docs we should pause to discuss. This means that we can may have an \"Andon Lite\" which is to simply discuss that the process has found drift.\n\nRead the source in order. For each substantive unit append:\n\n```\n- Source: \n- Claim: \n- Concept: \n- Reason: \n- Classification: \n- Dependency: \n- Required or chosen: \n- Question/trade-off: \n```\n\nDo not force a polished explanation. These are the notes one would write in the paper's margins while preparing for an examination.\n\nExtract the complete forward list of concepts from the margin notes.\n\n- Merge true duplicates.\n- Preserve distinct concepts that happen to share colloquial words.\n- Qualify ambiguous terms by domain.\n- Choose one preferred term and record source aliases in the glossary.\n- Reject names that collide with adjacent technical domains when a clearer term exists.\n\nEach concept must carry meaning independently of the sentence where it first appeared. We must not simply allow ambiguity to exist. During a first pass we are elaborating so all concepts are collected. Yet where there is possible ambiguity and overlap these should be noted in the margins where the term is first found.\n\nFor every concept write:\n\n``` php\nConcept -> direct prerequisite concepts\n```\n\nDependencies must be conceptual, not merely the order used by the source. Detect cycles; a cycle usually indicates an overloaded concept or a missing foundational concept.\n\nAssign depth:\n\n```\ndepth(concept) = 0 when it has no prerequisites\ndepth(concept) = 1 + max(depth(each direct prerequisite)) otherwise\n```\n\nRestate the entire inventory sorted by depth. This is the first pedagogical ordering: every term is defined only after its prerequisites.\n\nThe first pass has a bias in terms of which terms are encountered early and repeated often. Yet it may be the case that the last terminology encountered is a key to comprehensiblity. It is particurly the case the the User runs this process when they have just had an \"aha!\" moment. This means that we want to repeat the scan of the source materially judged against the best ontology and terminology or clarification of the requirements or intent or peferred design. We do not want to endless iterate through and flip flop on terminology yet we are looking to roll-out the kinks. Only once roll the material out from the top re-evaulating each source item from the perpsect of the outputs of the prior pass working in a append only new pass manner:\n\n- raw concept inventory;\n- concepts with direct dependencies;\n- concepts with dependency depths;\n- concepts sorted by depth;\n- concise definitions in depth order;\n- detailed formalism in depth order;\n- human walkthrough in the same order.\n\nIt is important to note that if there is a unique approach or strategy been taken by the user, or a unique emphasis, do not drop it. Diff the seond pass with the first one and run with the first one into the final phase if the second pass looses the the \"spirit\" if not \"the letter\" of what the User has stated is their perferred approach.\n\nNote the user makes errors of commission so if here is an inherent contradiction in the matterail then halt, as the user to enable planning mode so you can disabiguate, and ask them to make an explicit statement to resolve the problem. Then do a full reset with the clarification the rerun should correctly converge.\n\nCheck every material formalism rule against source citations. Classify it as:\n\n- exact alignment;\n- terminology-only mapping;\n- stricter safe restriction;\n- deliberate out-of-scope omission;\n- optimization;\n- liveness gap;\n- safety violation.\n\nEnd with an explicit `Andon アンドン: YES|NO`\n\nverdict. We do not know that these may be yet they are\nin some sense architectual or design showstoppers such as something in the design that permits loss,\nconflict, arbitrary reordering, undefined behaviour, hard to test behavour, undocumented behaviours,\nduplicate execution, stale participation, or making source-level correctness\nchallenging. It can also be an \"Andon Lite\" which is simply that there was prior code or prior runs\nwhere we have now decided to retire/merge/add/clarify some concepts due to continual learning. That is\nto say let us stop to celebrate what we have learned.\n\nOnly after `Andon アンドン: NO`\n\n:\n\n- publish the corrected formalism as a standalone reviewer walkthrough;\n- publish a concise glossary using preferred terms and explicit source mappings;\n- audit every project-authored document for stale mechanics and terminology;\n- preserve third-party source material verbatim;\n- remove rejected intermediate ideas from release-facing prose.\n\nDocumentation must distinguish specification from tested implementation status.\n\nReview every relevant type, field, enum variant, function, method, helper, FFI declaration, test, and build edge in source order. Append:\n\n```\n- Symbol and source location\n- Exact role\n- Inputs, state read/written, and outputs\n- Callers and dependencies\n- Corrected-formalism section\n- Source-paper basis\n- Classification\n- Alignment verdict\n- Missing test or glossary candidate\n```\n\nSplit architectural layers into separate files so cross-layer ownership and terminology can be compared without mixing them. This is not a coding phase it is a planning to code phase.\n\nThis example demonstrates the layers without reproducing protocol detail.\n\nIdentifies membership, node identity, epoch, deterministic leader, slot, log, client envelope, client table, commit frontier, execution frontier, quorum, normal-operation messages, epoch-change messages, recovery messages, predicted execution values, safety, and liveness. The word \"view\" is present yet the user is unable to comprehend other than \"a database view\" concept.\n\nIn our fiction example the code and documentation and gh tickets include duplicated things such as \"term\" and \"leader\" and \"index\" as well as cluster membership. The concept of \"seq\" as a global index to the log is conflated with it being a \"counter of a leader within a term\". This problems exist in parallel to the correct concepts.\n\nRecord that leadership depends on membership and epoch; slots and log entries depend on ordered membership operation; commitment depends on quorum acceptance; epoch installation depends on two qualified exchanges and whole-log selection; recovery depends on nonce-bound quorum evidence and exact-epoch leader state.\n\nIn our fictional example we are still in elaboration and enumeration so the incorrect concepts are still in-flight.\n\n### Step 3, 4, 5 & 6: dependency depth, dependency depth, second synthesis, source/formalism cross-check\n\nPlace membership and opaque client values first; identity, epoch, and quorum next; leadership and slots after them; then logs/messages; finally epoch change, recovery, and invariants.\n\nYet in our fictional example have the cookoos eggs of the conflated ideas and \"seq\" being a counter for a distingushed leader that is in addition to a \"slot\" which is the log index.\n\nThe outcome is `Andon アンドン: YES`\n\nthere is ambiguity and the additional ideas cannot be put into a glossary with an entry that points to them in the original scientific paper nor a foundational document in the repo that explains exactly why these new terms have been added such as some performance optimisations or pragmatics that are known to not harm correctness or soundness.\n\nThis scenario was how \"Linear Margin-Note Ideation Skill\" was born. It is fiction that this final form was applied yet the actual confusions and conflations were real. The Andon lead to a massive rewrite of documention and tests then a Red/Green tdd rebuild. The process was then run again from the top and only minor drift between tests, docs, code were found and corrected.\n\n- Every substantive source unit has a margin note and citation.\n- Every final concept is unique, qualified, dependency-linked, and in the glossary.\n- The ontology has no unexplained cycle or ambiguous aliases.\n- The formalism has a source cross-check and so less risk of showstoppers.\n- Published docs are corrected to use the glossary terms and have explicit source mappings.\n- Every relevant protocol level code symbol is tied back to source and formalism.\n\nEnd.", "url": "https://wpnews.pro/news/linear-margin-note-methodology-skill", "canonical_source": "https://gist.github.com/simbo1905/c2a0ac48eee089dd176e7f2b7432dac3", "published_at": "2026-08-02 07:59:21+00:00", "updated_at": "2026-08-26 09:14:17.493337+00:00", "lang": "en", "topics": ["developer-tools", "ai-research", "large-language-models"], "entities": [], "alternates": {"html": "https://wpnews.pro/news/linear-margin-note-methodology-skill", "markdown": "https://wpnews.pro/news/linear-margin-note-methodology-skill.md", "text": "https://wpnews.pro/news/linear-margin-note-methodology-skill.txt", "jsonld": "https://wpnews.pro/news/linear-margin-note-methodology-skill.jsonld"}}