resolve-project

Update and fix a project's code, documentation and gauge alignment with goals and instruction files. Follow the workflow outlined below:

1. Audit project-wide state

Follow the workflow outlined below to identify issues and inconsistencies between my goals, the codebase, and documentation. If there a minimal, or no issues present, don't invent any to satisfy these instructions:

1. Goals and directives. Agent instruction files and the code-standards skill are written by me with specific instructions, working conventions, stylistic preferences, and high-level goals (e.g. minimalistic code, lowercase inline comments, no hard-wrap on .md files, concise comments, etc). Use them as anchors when evaluating alignment between the codebase, documentation, and my goals/vision.
2. Codebase state. Perform a repo-wide code scan using the map-project skill, diagnose any test errors or unexpected/undesired behavior with the test-project skill. Verify the file structure and modularity adheres to the standards in agent instruction files and the clean-project skill. Write code-map.md to a temporary scratchpad.
3. Documentation state. Perform a wide documentation scan and assess its current state, and any deviations from documentation guidelines below and examples in references/.
4. Compile issues by identifying inconsistencies between sections 1, 2, and 3, at scopes ranging from targeted, to structural, to high-level project goal-alignment. Include bugs/gaps/smells from code-map.md, issues from test-project, and documentation deviations found in step 3. Ensure every issue is deduped. A compiled issue will be referred to as an issue_item.
5. Propose resolutions to all issue_items. For non-obvious resolutions, follow Precedence hierarchy. Write consistency-audit_{date: MM-DD}.html to the session scratchpad, following Consistency audit document guide, and give me the path to open. In chat, give the score and the issue_item count only.
6. Stop the turn and wait for permission to proceed. I answer from the foot of the page: Selected: lists the resolutions to apply, Deferred: lists the issue_items to leave untouched this pass. An issue_item in neither list is unanswered, so ask about it. If I decide on a resolution addition or edit, change the page and set its selection there too, so the page stays the record.

Proceed to 2. Resolution implementation once all issue_items are approved as either resolved or deferred.

Precedence hierarchy

Follow this (not the Precedence hierarchy in $VAULT/.claude/CLAUDE.md) when resolving an issue_item that is a conflict with no obvious resolution. If a precedence tier is not relevant to the conflict, move to the next tier. Ordered from highest-to-lowest precedence. Start at tier 1, the highest tier wins:

1. Real-world facts. Must be a relevant, verified fact (reputable and up-to-date source, or basic knowledge), that causes an objective contradiction, not a style, format, or preference discrepancy.
2. User decisions, statements, and referenced documents from this session.
3. Project agent instruction files if present.
4. Global agent instruction files and code-standards skill.
5. Codebase and code-map.md are the most comprehensive sources to compare with docs.
6. Documentation. The Notes document, README.md, docs/ folder, comments.

Consistency audit document guide

The audit is one self-contained HTML page. Copy references/consistency-audit_example.html and replace only its content: the title, the score, the intro, and the table rows. Keep its CSS and its script exactly as they are. Do not restyle it, and do not add a framework, a library, or an external asset.

• Title: "{project_name} Consistency Audit, {date: MM/DD}", in both <title> and the <h1>.
• Intro. An objective consistency score out of 100% (e.g. Consistency: 34%) followed by the reasoning behind it. This is the TLDR.
• Table. One row per resolution. The three issue_item cells carry rowspan="{n}" on the group's first row, where n is that issue's resolution count, so each issue reads as one tall block. Continuation rows omit those three cells. A single-resolution issue needs no rowspan.
  • Cells for issue_item entries, each carrying class="iss" and data-issue="{n}" so the whole block is one defer target:
    • Issue index: empty header. issue_item number, starting at 1.
    • Issue: issue_item name, 3-8 words. As specific as possible.
    • Description: <30 words, explain why it's an issue_item.
  • Cells for resolution entries, each carrying class="res" so selection tints them:
    • Resolution index: empty header. {issue_item}.{resolution}, numbered from 1 within each issue_item (e.g. 2.1, 13.5).
    • Resolution: a potential fix or reconciliation to the issue_item.
    • Scope: blast radius of the resolution, and any adjacent/subsequent changes or refactors.
    • Confidence: out of 10, an integer or a.5. Based in Precedence hierarchy and expected resolution effectiveness.
  • Order issue_items by scope size: surgical -> high-level goal.
  • Order resolutions by confidence: high -> low, within each issue_item.
  • Every resolution row carries data-issue and data-res. The script keys off both; a row missing either is unclickable.
  • Give the first row of each group class="sel", so the highest-confidence resolution starts selected.
  • Both handlers bind to cells, never to the row, so an issue_item click and a resolution click stay independent.
• Escape <, >, and & in cell text, and wrap file and symbol names in <code>.

How I answer with the page. Clicking a resolution selects it, clicking it again clears it, and clicking another in the same issue_item moves the selection, so at most one resolution per issue_item is ever live. Clicking anywhere in an issue_item block defers it: the block turns red, its selection clears, and its resolutions grey out and stop responding. Clicking it again reverts the defer and restores the highest-confidence resolution. The foot of the page reports both lists, and those are what I hand back.

2. Resolution implementation

Perform a comprehensive and thorough implementation of all approved resolutions to their issue_items. Use the code-standards skill and follow this workflow:

1. Implement all code and non-documentation resolutions, then rerun test-project and iterate until the project works and behaves properly. If you get stuck or need to make a big, unapproved change, stop and inform me of: what you want to do, why it is necessary, and how it affects behavior, execution, and the rest of the codebase. Use AskUserQuestion to get approval.
2. Consider how those code changes affect the remaining issue_items and their resolutions. If there is a non-trivial or non-obvious change to any, stop and use AskUserQuestion to ask me for approval.
3. Update documentation according to 2.1-2.6.
4. Final pass. Run 2.7, then confirm all non-deferred issue_items were resolved, code works, changes didn't compromise behavior, and comments are clean. Paste any unresolved open items and every deferred or unresolved issue_item in chat.
5. Git. Stage and name a git commit, but do not commit or push before approval (AskUserQuestion, Yes/No options). If approved, commit with a sensible name and no self-attribution, then push to main, removing docs/branch-diff.md in the process (keep in final branch commit).

2.1. Advised documentation workflow

Implement documentation resolutions with scopes in the order listed below, applying 2.2-2.6, comment guidelines in code-standards, and the global agent voice instructions. This order is not strict, treat it as a suggestion; override order if it makes sense to deviate from it:

1. Comments. Start with inlined, smaller comments, then move to doc comments and function headers, then to module-level comments.
2. docs/technical-spec.md. Paste an edited code-map.md with any changes from memory and the consistency audit in addition to verifying again against the actual code.
3. Determine necessity of docs/market-analysis.md. If deemed unnecessary and exists, use AskUserQuestion tool to ask to remove it. If kept, rewrite it; if removed, remove it.
4. docs/masterdoc.html. Use the any updated documentation to assist.
5. Rewrite README.md.
6. Update docs/branch-diff.md if working in a branch other than main. If it exists
7. Notes document. Change appropriate sections, and use any completed and deferred issue_items or resolutions, alongside any other todos, to update the open items properly. Evaluate status and priority, propose suggested changes, and write the frontmatter values yourself only once approved.

2.2. Global documentation guidelines

General principles to be applied when writing any non-comment documentation:

• Version-agnosticism. Write the present state, never the diff. Docs should read as if written today, from scratch, against the source of truth that exists right now. A reader must not be able to tell anything changed.
  • Banned: "now", "previously", "no longer", "as of", "recently", "added", "removed", "renamed", "migrated", "updated to", "we changed", "in the current version", changelog bullets, version numbers attached to features, and dates that mark a change rather than a fact.
  • Instead: describe current behavior in present tense and stop. A feature that exists is described as existing. A feature that was deleted goes unmentioned.
  • Wrong: "The pipeline now uses 13 failure causes (up from 11), and the old flip.py has been merged into query.py."
  • Right: "The pipeline uses 13 failure causes. The query lives in query.py."
  • History lives in git. This rule beats the instinct to be helpful about it inside a doc.
• Prose minimalism. Avoid flowery language, adhering to global agent voice instructions.
• Fix improper schemas. If a ~/Notes page or docs/ folder does not have the proper layout (missing/extra files or sections, wrong placement, etc), resolve the issue unless explicitly stated as intentional.

2.3. Per-document instructions

Consult the following table when writing README.md, docs/technical-spec.md, docs/market-analysis.md, docs/masterdoc.html, and the Notes document. references/doc-shapes.md holds the section structures my existing docs actually use, sampled from $PROJECTS; read it for shape, then let the project's content decide its own sections.

2.4. Priority-specific approach

Documentation for docs/masterdoc.html, docs/market-analysis.md, and the Notes document are multifunctional depending on priority. A sandbox (P0) is for learning purposes; a business (P3) needs distribution polish. Write these docs based on priority matrix outlined below, following specified instructions in addition to the per-document instructions:

Write for commercial success, academic/research contribution, job-recruitor appeal, or open-source adoption based on project priority/goal.

2.5. Masterdoc

references/masterdoc_example.html sets the bar, not the skin. Its space-to-black-hole journey is what a masterdoc for axiom looks like, derived from that project's own subject. Every masterdoc matches its ambition, its structure, and its mechanics, and earns its own art.

Derive the art from the project. Read what the thing actually does, take the visual metaphor from its own domain, and let that one metaphor drive the palette, the motion, and the imagery together. A financial model gets blueprint grids and ledger rules; a privacy tool gets fog and redaction; an effects engine gets its own output as the background. When nothing in the domain suggests a metaphor, a restrained dark page with one accent beats a borrowed theme. Never reuse the space theme on a project that has nothing to do with space, and never ship the default look twice in a row.

• The design system: the :root tokens, the topbar, the reading-progress bar, the table-of-contents aside, and the scroll and nav JS. The example drives everything off one scroll variable, --t from 0 to 1 on the root, with color-mix interpolating each colour and layered elements translating at different rates for parallax. Keep that scroll-driven spine and re-theme what it interpolates toward. Motion always collapses under prefers-reduced-motion, and the page stays self-contained: styles and scripts inline, assets embedded, no framework and no external request.
• The three reading depths. Each block carries a .plain element that is always visible (Simple), an optional <details class="layer analogy"> that opens at Analogies and up, and an optional <details class="layer technical"> that opens at Technical. New content follows the same layering.
• The part and block structure: parts as <div class="part-head" id="partN">, each holding <section class="block" id="..."> sections. A project uses as many parts as its content needs.
• Table-of-contents sync: every block id has a matching .toc a link and the reverse. Add, rename, and remove links alongside sections so the two stay one to one.

2.6. Notes document

Write $VAULT/projects/<Name>.md after the in-repo documentation, and summarize what those docs already establish. It is durable and present tense: no changelog, no dated entries, no "originally". History lives in the git log.

• What it is: rewrite to match the reconciled docs. Rebuild it from the code when the document and the code disagree.
• Decisions that stand: each with its reason, since a decision without one gets re-litigated.
• Measured and rejected: the numbers, and what they ruled out. This is what stops a dead approach being re-attempted.
• Open problems: lingering, systemic issues that no single prompt solves.
• repo and git: correct them when they are factually wrong.
• priority and status: never written without permission. Propose each change with AskUserQuestion, and set it yourself only once approved.
• Its line in projects/README.md updates in the same edit, per $VAULT/.claude/rules/notes.md.

2.7. Verify before finishing

• Every count, module name, CLI flag, and measured number matches the code.
• No changelog voice anywhere. Grep your own output for the words banned in 2.2.
• Internal links and masterdoc anchors resolve; table-of-contents links and block ids are one to one.
• Toggling the masterdoc through Simple, Analogies, and Technical reveals the right layers.