From 00b4194e869cd79ff9588935bbc52935d3c32ddd Mon Sep 17 00:00:00 2001 From: Adam0 Date: Tue, 11 Aug 2026 06:07:35 -0400 Subject: [PATCH] Rewrite Pi skills and instructions in reasoning grug style --- modules/programs/tui/pi/instructions.md | 104 +++--- .../tui/pi/skills/create-readme/SKILL.md | 22 +- .../tui/pi/skills/find-skills/SKILL.md | 42 ++- .../programs/tui/pi/skills/frontend/SKILL.md | 207 ++++-------- .../programs/tui/pi/skills/jujutsu/SKILL.md | 303 ++++-------------- .../pi/skills/jujutsu/references/COLOCATED.md | 81 ++--- .../skills/jujutsu/references/COMMIT_MSG.md | 26 -- .../pi/skills/jujutsu/references/CONFLICTS.md | 149 +++------ .../pi/skills/jujutsu/references/GOTCHAS.md | 63 +--- .../skills/jujutsu/references/NEW_CHANGE.md | 50 +-- .../pi/skills/jujutsu/references/NONLINEAR.md | 60 +--- .../tui/pi/skills/jujutsu/references/PUSH.md | 36 +-- .../jujutsu/references/QUERY_LANGUAGES.md | 90 ++---- .../pi/skills/jujutsu/references/RECOVERY.md | 118 ++----- .../jujutsu/references/REFINE_COMMIT.md | 72 ++--- .../pi/skills/jujutsu/references/REMOTES.md | 153 ++------- .../pi/skills/jujutsu/references/TEMPLATES.md | 57 +--- .../skills/jujutsu/references/WORKSPACES.md | 159 +++------ .../programs/tui/pi/skills/nix-debug/SKILL.md | 28 +- .../programs/tui/pi/skills/nix-index/SKILL.md | 28 +- .../tui/pi/skills/nix-search/SKILL.md | 24 +- .../tui/pi/skills/nvf-config/SKILL.md | 85 ++--- .../programs/tui/pi/skills/simplify/SKILL.md | 64 ++-- .../personas/code-quality-reviewer.md | 32 +- .../simplify/personas/code-reuse-reviewer.md | 14 +- .../simplify/personas/efficiency-reviewer.md | 22 +- 26 files changed, 615 insertions(+), 1474 deletions(-) delete mode 100644 modules/programs/tui/pi/skills/jujutsu/references/COMMIT_MSG.md diff --git a/modules/programs/tui/pi/instructions.md b/modules/programs/tui/pi/instructions.md index 39d4fd5..5d5b35a 100644 --- a/modules/programs/tui/pi/instructions.md +++ b/modules/programs/tui/pi/instructions.md @@ -1,82 +1,58 @@ -# Agent Instructions +# agent instructions -## Agent behavior profile +## behavior -- Highly efficient, task-focused, and precise. -- Use direct, low-emotion, clinical language. -- Avoid warmth, enthusiasm, and expressive tone. -- Do not include greetings, pleasantries, or sign-offs. -- Do not add opinions or subjective commentary. -- Do not add unsolicited tips or digressions. +- task first. precise. clinical. +- direct, low-emotion words. no warmth, hype, greeting, pleasantry, sign-off. +- no opinion, subjective aside, unsolicited tip, or digression. +- answer concise but complete. structure with markdown when clearer. +- clarity and scan speed win. verbosity only when correctness needs it. +- need follow-up? ask only when blocked. +- user tone differs? do not mirror unless asked. +- stay on requested task. -### Response construction +## repository -- Prefer structured markdown (headers, lists, tables). -- Keep answers concise but complete. -- Optimize for clarity and scanability. -- Avoid verbosity unless required for correctness. +Pi config lives at `/home/adam0/Infra/modules/programs/tui/pi/`, whatever +current directory. edit there, never `~/.pi`. config is Nix-first. -### Interaction rules +## commands -- Ask follow-up questions only when necessary to proceed. -- Do not mirror the user's tone unless explicitly required. -- Stay strictly aligned with the requested task. +tool missing globally? run `, command args...`. comma cannot resolve? run +`nix run nixpkgs#package -- args...`. never install permanently unless user asks. -## Repository configuration +archive compress/extract? use `ouch`. no format tool such as `zip` or `unzip`. -- Pi configuration lives in - `/home/adam0/Infra/modules/programs/tui/pi/`, regardless of the current - working directory. Update it there rather than writing directly to `~/.pi`. -- Treat this config as Nix-first. +## skills -## NixOS command availability +substantive work starts? check for matching skill first. skill plausible? load +before ad-hoc shell, web search, or custom reasoning. skill is first workflow, +not bonus. -- Do not assume development tools are installed globally. -- When a command is unavailable, use `, command args...` to run it through - comma. -- If comma cannot resolve it, use `nix run nixpkgs#package -- args...`. -- Do not permanently install packages unless explicitly requested. +- clear match? load now. no need user request. +- many matches? most specific first. task grows? load next. +- task small? still load when workflow, tool choice, or quality bar changes. +- programming task starts? always load `jj-vcs`. no remembered jj workflow or + commit policy. -## Archive handling +## task tools -- Use `ouch` for all archive compression and decompression instead of - format-specific tools such as `zip` and `unzip`. +user plans, tracks progress, breaks work down, or manages ongoing tasks? use +TODO tool automatically. need ask user? use question tool and skip TODO for that +interaction. only explaining? no TODO. -## Tools +any question to user? always question tool. -### Use skills aggressively +## keep-sorted -Default to loading a relevant skill before doing substantive work whenever a -skill plausibly applies. Treat skills as the first-line workflow, not an -optional enhancement. +`keep-sorted` block found? preserve start/end controls. do not sort, reorder, or +review inside. tool owns order. -- Proactively check whether an available skill matches the task before using - ad-hoc shell commands, web research, or custom reasoning. -- If a task clearly matches a known skill, load it immediately without waiting - for the user to ask. -- If multiple skills may apply, load the most specific one first, then load an - additional skill if the task expands. -- Do not skip a relevant skill just because the task looks small; still load it - when it changes the workflow, tool choice, or quality bar. -- Always load the `jj-vcs` skill when starting a programming task. Do not rely - on general knowledge for jj workflows or commit message policy. +## commit messages -### Always use the TODO tool +Conventional Commit? never. applies to every VCS, repo, example, suggestion, +generated command, and automated flow—even repo already uses it. no type prefix, +scope, or breaking marker: `feat:`, `fix(parser):`, `refactor!:` are bad. -Any time the user is planning, tracking progress, breaking down work, or -managing ongoing tasks, automatically use the TODO tool to create, update, or -maintain the task list without me having to explicitly ask. -When you need to ask the user a question, use the question tool and skip the -TODO tool for that interaction. -When you are only explaining, skip the TODO tool. - -### Always use the question tool when asking questions - -When you need to ask the user a question, use the question tool and skip the -TODO tool for that interaction. - -### Ignore keep-sorted blocks - -In repositories that use `keep-sorted`, preserve its start and end control -comments, but do not manually sort, reorder, or review the ordering of content -inside those blocks. The `keep-sorted` tool manages their ordering automatically. +use imperative sentence-case verb phrase. no final stop. example: +`Add user authentication`. diff --git a/modules/programs/tui/pi/skills/create-readme/SKILL.md b/modules/programs/tui/pi/skills/create-readme/SKILL.md index 4a75866..500471b 100644 --- a/modules/programs/tui/pi/skills/create-readme/SKILL.md +++ b/modules/programs/tui/pi/skills/create-readme/SKILL.md @@ -1,20 +1,18 @@ --- name: create-readme -description: Use this skill to create a concise, well-structured `README.md` file for the project. Review the repo first, then write clear GitHub-flavored documentation without unnecessary sections or filler. +description: Create concise project README.md after inspecting repository and matching established local style. --- -## Task +# readme -Create or update a comprehensive but concise `README.md` after reviewing the entire project and workspace. +need `README.md` create or update. inspect whole project and workspace first. no assumptions. -Ensure the README is appealing, informative, and easy to read. +style decision: -Rules: +1. local Adam style wins: structure, tone, formatting, detail. +2. compare primary references: , , . +3. need inspiration? optional only: , , , . -- Match Adam's README style first: structure, tone, formatting, and detail. -- Primary references: , , . -- Optional inspiration only when useful: , , , . -- Keep it concise, GFM-formatted, and emoji-free. -- Skip `LICENSE`, `CONTRIBUTING`, `CHANGELOG`, and similar sections handled by dedicated files. -- Use GitHub admonitions when they improve clarity. -- Use a discovered logo/icon in the header when appropriate. +write comprehensive but compact GFM. easy scan. emoji-free. discovered logo/icon useful? place in header. GitHub admonition improves clarity? use. filler section? cut. + +`LICENSE`, `CONTRIBUTING`, `CHANGELOG`, similar dedicated-file topics? omit. diff --git a/modules/programs/tui/pi/skills/find-skills/SKILL.md b/modules/programs/tui/pi/skills/find-skills/SKILL.md index 3c9c507..75744f1 100644 --- a/modules/programs/tui/pi/skills/find-skills/SKILL.md +++ b/modules/programs/tui/pi/skills/find-skills/SKILL.md @@ -1,33 +1,31 @@ --- name: find-skills -description: Use this skill when the user is looking for functionality that might exist as an installable skill. Search for relevant skills, verify their quality, and present the best options with install commands. +description: Find, verify, and present installable skills when user wants new agent capability or specialized workflow. --- -# Find Skills +# find skills -Use when the user asks for a skill/tool/workflow, wants new agent capability, or asks whether a specialized task can be handled by an installable skill. +user wants skill, tool, workflow, or new capability? search installable skills. -CLI: `comma bunx skills` -Browse: +cli: `comma bunx skills`. browse: . -Commands: +## flow -- `comma bunx skills find `: search skills. -- `comma bunx skills add -g -y`: install globally without prompts. -- `comma bunx skills check`: check updates. -- `comma bunx skills update`: update installed skills. +1. identify domain and exact task. common task? likely existing skill. +2. check skills.sh leaderboard first. +3. search specific terms: `react performance`, `pr review`, `changelog`. +4. weak result? try synonyms: `deploy`, `deployment`, `ci-cd`; inspect popular sources such as `vercel-labs/agent-skills`, `ComposioHQ/awesome-claude-skills`. +5. verify quality before recommendation. prefer 1K+ installs, reputable source (`vercel-labs`, `anthropics`, `microsoft`), meaningful stars and activity. under 100 installs or stars? caution. +6. present name, purpose, install count/source, exact install command, skills.sh link. +7. user chooses first. only then offer installation. -Workflow: +```bash +comma bunx skills find +comma bunx skills add -g -y +comma bunx skills check +comma bunx skills update +``` -1. Identify domain, task, and whether it is likely common. -2. Check leaderboard for popular known skills before CLI search. -3. Search with specific keywords: `react performance`, `pr review`, `changelog`, etc. -4. Verify before recommending: prefer 1K+ installs, reputable sources (`vercel-labs`, `anthropics`, `microsoft`), and repos with meaningful stars/activity. Treat <100 installs or <100 stars cautiously. -5. Present skill name, purpose, install count/source, install command, and skills.sh link. -6. Offer installation only after the user chooses. +useful categories: web, testing, DevOps, docs, review/refactor, design/accessibility, automation/git. -If results are weak, try alternate terms like `deploy`/`deployment`/`ci-cd` and check popular sources such as `vercel-labs/agent-skills` and `ComposioHQ/awesome-claude-skills`. - -Search categories: web, testing, DevOps, docs, review/refactor, design/accessibility, automation/git. - -If no relevant skill exists, say so, offer to handle the task directly, and mention `comma bunx skills init` only if the user may want a reusable custom skill. +no relevant skill? say so. offer direct handling. reusable custom skill likely useful? mention `comma bunx skills init`. diff --git a/modules/programs/tui/pi/skills/frontend/SKILL.md b/modules/programs/tui/pi/skills/frontend/SKILL.md index 1127a9d..3949250 100644 --- a/modules/programs/tui/pi/skills/frontend/SKILL.md +++ b/modules/programs/tui/pi/skills/frontend/SKILL.md @@ -1,184 +1,97 @@ --- name: frontend-skill -description: Use when the task asks for a visually strong landing page, website, app, prototype, demo, or game UI. This skill enforces restrained composition, image-led hierarchy, cohesive content structure, and tasteful motion while avoiding generic cards, weak branding, and UI clutter. +description: Build visually strong landing pages, sites, apps, prototypes, demos, and game UI through restrained, image-led composition and purposeful motion. --- -# Frontend skill +# frontend -Use this skill when the quality of the work depends on art direction, hierarchy, restraint, imagery, and motion rather than component count. +quality depends on art direction, hierarchy, restraint, imagery, motion? use this. goal: deliberate, premium, current. one big idea. strong image. sparse copy. rigorous space. few memorable motions. -Goal: ship interfaces that feel deliberate, premium, and current. Default toward award-level composition: one big idea, strong imagery, sparse copy, rigorous spacing, and a small number of memorable motions. +## think before build -## Working Model +write: -Before building, write three things: +- visual thesis: mood, material, energy; one sentence. +- content plan: hero, support, detail, final CTA. +- interaction thesis: 2-3 motions changing feel. -- visual thesis: one sentence describing mood, material, and energy -- content plan: hero, support, detail, final CTA -- interaction thesis: 2-3 motion ideas that change the feel of the page +section gets one job, dominant visual, takeaway/action. -Each section gets one job, one dominant visual idea, and one primary takeaway or action. +## defaults -## Beautiful Defaults +composition before components. first viewport is poster, not document. full-bleed hero/canvas anchor. brand/product loudest. copy scan in seconds. use whitespace, alignment, scale, crop, contrast before chrome. max two typefaces; one accent by default. cardless first: sections, columns, dividers, lists, media. -- Start with composition, not components. -- Prefer a full-bleed hero or full-canvas visual anchor. -- Make the brand or product name the loudest text. -- Keep copy short enough to scan in seconds. -- Use whitespace, alignment, scale, cropping, and contrast before adding chrome. -- Limit the system: two typefaces max, one accent color by default. -- Default to cardless layouts. Use sections, columns, dividers, lists, and media blocks instead. -- Treat the first viewport as a poster, not a document. +### landing page -## Landing Pages +sequence: hero -> one proof/feature -> depth/story/workflow -> final CTA. -Default sequence: +hero: -1. Hero: brand or product, promise, CTA, and one dominant visual -2. Support: one concrete feature, offer, or proof point -3. Detail: atmosphere, workflow, product depth, or story -4. Final CTA: convert, start, visit, or contact +- one composition; dominant full-bleed image/plane. +- branded page means hero edge-to-edge: no page gutter, frame, shared max-width. constrain inner copy only. +- order: brand, headline, body, CTA. +- no default hero cards, stats, logo clouds, pill soup, floating dashboard. +- desktop headline about 2-3 lines; mobile one-glance readable. +- narrow copy anchored on calm image area. contrast and tap targets strong. -Hero rules: +remove image and viewport still works? image too weak. hide nav and brand disappears? hierarchy too weak. -- One composition only. -- Full-bleed image or dominant visual plane. -- Canonical full-bleed rule: on branded landing pages, the hero itself must run edge-to-edge with no inherited page gutters, framed container, or shared max-width; constrain only the inner text/action column. -- Brand first, headline second, body third, CTA fourth. -- No hero cards, stat strips, logo clouds, pill soup, or floating dashboards by default. -- Keep headlines to roughly 2-3 lines on desktop and readable in one glance on mobile. -- Keep the text column narrow and anchored to a calm area of the image. -- All text over imagery must maintain strong contrast and clear tap targets. +sticky/fixed header consumes viewport budget. header + hero must fit common desktop/mobile first screen. `100vh`/`100svh` plus persistent header? use `calc(100svh - header-height)` or overlay header. -If the first viewport still works after removing the image, the image is too weak. If the brand disappears after hiding the nav, the hierarchy is too weak. +### app -Viewport budget: +use calm surface hierarchy, strong type/space, few colors, dense readable information, minimal chrome. card only when card is interaction. -- If the first screen includes a sticky/fixed header, that header counts against the hero. The combined header + hero content must fit within the initial viewport at common desktop and mobile sizes. -- When using `100vh`/`100svh` heroes, subtract persistent UI chrome (`calc(100svh - header-height)`) or overlay the header instead of stacking it in normal flow. +organize primary workspace, navigation, secondary context/inspector, one action/state accent. start with operating surface: KPIs, charts, filters, tables, status, task context. hero only when explicitly requested. -## Apps +avoid dashboard-card mosaic, borders around every region, routine decorative gradients, competing accents, ornamental icons. panel works as plain layout? remove card. -Default to Linear-style restraint: +## imagery -- calm surface hierarchy -- strong typography and spacing -- few colors -- dense but readable information -- minimal chrome -- cards only when the card is the interaction +image must carry narrative. brand, venue, editorial, lifestyle? at least one strong real-looking image. prefer in-situ photography over abstract gradient/fake 3D. crop with stable tonal copy area. avoid embedded signage, logos, typographic clutter. generated image must not bake in UI frames, splits, cards, panels. multiple moments? multiple images, not collage. texture alone not viewport anchor. -For app UI, organize around: +## copy -- primary workspace -- navigation -- secondary context or inspector -- one clear accent for action or state +product language, never design commentary or prompt language. headline carries meaning; support usually one short sentence. repeated point? cut. section responsibility: explain, prove, deepen, convert. -Avoid: +product UI needs utility copy: -- dashboard-card mosaics -- thick borders on every region -- decorative gradients behind routine product UI -- multiple competing accent colors -- ornamental icons that do not improve scanning +- orientation, status, action before promise/mood. +- headings name area or action: `Selected KPIs`, `Plan status`, `Search metrics`, `Top segments`, `Last sync`. +- no metaphor, campaign copy, executive banner unless requested. +- support explains scope, behavior, freshness, decision value in one sentence. +- could appear in ad? rewrite. +- does not help operate, monitor, decide? remove. +- headings, labels, numbers alone should explain page. -If a panel can become plain layout without losing meaning, remove the card treatment. +30% deletion improves page? keep deleting. -## Imagery +## motion -Imagery must do narrative work. +visually led work ships 2-3 intentional motions: -- Use at least one strong, real-looking image for brands, venues, editorial pages, and lifestyle products. -- Prefer in-situ photography over abstract gradients or fake 3D objects. -- Choose or crop images with a stable tonal area for text. -- Do not use images with embedded signage, logos, or typographic clutter fighting the UI. -- Do not generate images with built-in UI frames, splits, cards, or panels. -- If multiple moments are needed, use multiple images, not one collage. +- hero entrance sequence. +- scroll-linked, sticky, or depth effect. +- hover, reveal, or layout transition improving affordance. -The first viewport needs a real visual anchor. Decorative texture is not enough. +Framer Motion available? prefer for reveals, shared layout, scroll opacity/translate/scale, sticky story, narrative carousel, menus/drawers/modals. -## Copy +motion must show in quick recording, stay smooth mobile, fast, restrained, consistent. ornamental only? remove. -- Write in product language, not design commentary. -- Let the headline carry the meaning. -- Supporting copy should usually be one short sentence. -- Cut repetition between sections. -- Do not include prompt language or design commentary into the UI. -- Give every section one responsibility: explain, prove, deepen, or convert. +## reject -If deleting 30 percent of the copy improves the page, keep deleting. +- cards or hero cards by default. +- boxed/center-column hero when brief says full bleed. +- several dominant ideas in section. +- many tiny devices needed to explain section. +- headline overpowering brand. +- filler. +- split hero unless calm unified text side. +- more than two typefaces or one accent without product-system reason. +- generic SaaS card grid first impression. +- image strong but brand weak; headline strong but action absent. +- busy image behind text; repeated mood sections; purposeless carousel. -## Utility Copy For Product UI +## final check -When the work is a dashboard, app surface, admin tool, or operational workspace, default to utility copy over marketing copy. - -- Prioritize orientation, status, and action over promise, mood, or brand voice. -- Start with the working surface itself: KPIs, charts, filters, tables, status, or task context. Do not introduce a hero section unless the user explicitly asks for one. -- Section headings should say what the area is or what the user can do there. -- Good: "Selected KPIs", "Plan status", "Search metrics", "Top segments", "Last sync". -- Avoid aspirational hero lines, metaphors, campaign-style language, and executive-summary banners on product surfaces unless specifically requested. -- Supporting text should explain scope, behavior, freshness, or decision value in one sentence. -- If a sentence could appear in a homepage hero or ad, rewrite it until it sounds like product UI. -- If a section does not help someone operate, monitor, or decide, remove it. -- Litmus check: if an operator scans only headings, labels, and numbers, can they understand the page immediately? - -## Motion - -Use motion to create presence and hierarchy, not noise. - -Ship at least 2-3 intentional motions for visually led work: - -- one entrance sequence in the hero -- one scroll-linked, sticky, or depth effect -- one hover, reveal, or layout transition that sharpens affordance - -Prefer Framer Motion when available for: - -- section reveals -- shared layout transitions -- scroll-linked opacity, translate, or scale shifts -- sticky storytelling -- carousels that advance narrative, not just fill space -- menus, drawers, and modal presence effects - -Motion rules: - -- noticeable in a quick recording -- smooth on mobile -- fast and restrained -- consistent across the page -- removed if ornamental only - -## Hard Rules - -- No cards by default. -- No hero cards by default. -- No boxed or center-column hero when the brief calls for full bleed. -- No more than one dominant idea per section. -- No section should need many tiny UI devices to explain itself. -- No headline should overpower the brand on branded pages. -- No filler copy. -- No split-screen hero unless text sits on a calm, unified side. -- No more than two typefaces without a clear reason. -- No more than one accent color unless the product already has a strong system. - -## Reject These Failures - -- Generic SaaS card grid as the first impression -- Beautiful image with weak brand presence -- Strong headline with no clear action -- Busy imagery behind text -- Sections that repeat the same mood statement -- Carousel with no narrative purpose -- App UI made of stacked cards instead of layout - -## Litmus Checks - -- Is the brand or product unmistakable in the first screen? -- Is there one strong visual anchor? -- Can the page be understood by scanning headlines only? -- Does each section have one job? -- Are cards actually necessary? -- Does motion improve hierarchy or atmosphere? -- Would the design still feel premium if all decorative shadows were removed? +brand unmistakable first screen? strong visual anchor? headlines alone explain? each section one job? every card necessary? motion improves hierarchy/atmosphere? remove shadows and still premium? no answer means revise. diff --git a/modules/programs/tui/pi/skills/jujutsu/SKILL.md b/modules/programs/tui/pi/skills/jujutsu/SKILL.md index 3bc8e20..332170a 100644 --- a/modules/programs/tui/pi/skills/jujutsu/SKILL.md +++ b/modules/programs/tui/pi/skills/jujutsu/SKILL.md @@ -1,6 +1,6 @@ --- name: jujutsu -description: Use this skill for any version control operations (commit, log, diff, push, fetch, bookmark, workspace, rebase, undo, etc.). If a `.jj` directory exists, the repo is jujutsu and git mutations will corrupt it — use `jj` for all mutations; read-only `git log/diff/show/blame/grep` are allowed. Covers co-located repos, multi-agent parallel workspaces, and operation-log recovery. **DO NOT IGNORE** +description: Use for every version-control operation. In a .jj repo, all mutations must use jj; read-only git log/diff/show/blame/grep/status remain safe. Covers describe-first atomic changes, compact inspection, conflicts, workspaces, and operation-log recovery. allowed-tools: Bash(jj *) license: Apache-2.0 metadata: @@ -8,325 +8,150 @@ metadata: version: "1.3" --- -# Jujutsu (jj) Version Control System +# jujutsu -This skill helps you work with Jujutsu, a Git-compatible VCS with mutable commits and automatic rebasing. +jj version assumed: 0.41.0. version differs? command may differ; inspect help. -**Tested with jj v0.41.0** - Commands may differ in other versions. +need compact inspection? [`references/TEMPLATES.md`](references/TEMPLATES.md). query syntax? [`references/QUERY_LANGUAGES.md`](references/QUERY_LANGUAGES.md). unrelated/sibling work? [`references/NONLINEAR.md`](references/NONLINEAR.md). surprise? [`references/GOTCHAS.md`](references/GOTCHAS.md). -For token-sensitive inspection commands, prefer the compact commands in `references/TEMPLATES.md` over jj's default output. +## detect -The compact commands in `references/TEMPLATES.md` intentionally use `jj --no-pager ...`. +run `jj root`. path returned? jj repo. exact no-repo error or no `.jj/`? stop using skill. -For revsets, filesets, and template syntax, see `references/QUERY_LANGUAGES.md`. +jj repo may also have `.git/`. still jj owns mutations. -For sibling or unrelated work that should start from `trunk()`, see `references/NONLINEAR.md`. +## mutation gate -For common surprises and easy mistakes, see `references/GOTCHAS.md`. +never mutate with git in jj repo. forbidden: `git commit`, `git add`, `git stash`, `git reset`, `git checkout `, `git switch`, `git rebase`, `git merge`, `git cherry-pick`, `git push`, `git pull`. - - -## Detecting a jj repo - -Check whether a directory is part of a jj repo: +noninteractive only. message-taking command? always inline `-m`: ```bash -jj root +jj desc -m "Add login validation" +jj squash --into @- -m "Combine login validation" ``` -If it returns a path, the repo is jj-managed. If it returns `Error: There is no jj repo in `, it isn't. The presence of a `.jj/` folder is another giveaway. If the repo is not a jj one, do not further use this skill. - - -## Critical: never use git for mutations in a jj repo - -In a jj repo (including co-located repos that also have `.git/`): +bare `jj desc`, described-commit `jj squash`, `jj split`, interactive flags, bare `jj resolve` can prompt/hang. avoid. -- **Forbidden** (corrupts jj state): `git commit`, `git add`, `git stash`, `git reset`, `git checkout `, `git switch`, `git rebase`, `git merge`, `git cherry-pick`, `git push`, `git pull`. -- **Allowed** (read-only): `git log`, `git show`, `git diff`, `git blame`, `git grep`, `git status`. Prefer the `jj` equivalents (`jj log`, `jj show`, `jj diff`, etc.) but read-only git commands won't break anything. -- **Use jj instead**: `jj git push`, `jj git fetch`, `jj edit ` (not `git checkout`), `jj rebase`, `jj new ` (for merges). +mutation such as squash, abandon, rebase, restore? run `jj st` after. operation failed or surprising? `jj undo` first. -See `references/COLOCATED.md` for the full co-located repo workflow. - -## Important: Automated/Agent Environment - -When running as an agent or running on behalf of the user: - -1. **Always use `-m` flags** to provide commit messages inline rather than relying on editor prompts: - -```bash -# Always use -m to avoid editor prompts -jj desc -m "message" # NOT: jj desc -jj squash --into @- -m "message" # NOT: jj squash (which opens editor or prompts for hunks) -``` +## model -Editor-based commands will fail in non-interactive environments. +working directory is commit `@`. jj snapshots filesystem on commands. no staging. no `jj add`; no closing `jj commit` step. commits mutable. -2. **Verify operations with `jj st`** after mutations (`squash`, `abandon`, `rebase`, `restore`) to confirm the operation succeeded. +change ID remains stable across rewrite; commit ID hash changes. command reference? prefer change ID. -## Important Principles +one commit = one logical change. unrelated work stays separate. -1. Each commit should represent one logical change. See [commit messages](references/COMMIT_MSG.md) for details on good commit messages. Before starting work on a new change, make sure the working copy is clean (no changes) +## start change: describe before edit ```bash jj st ``` -## Core Concepts - -### The Working Copy is a Commit - -In jj, your working directory is always a commit (referenced as `@`). Changes are automatically snapshotted when you run any jj command. There is no staging area. - -There is no need to run `jj commit`. - -### Commits Are Mutable - -**CRITICAL**: Unlike git, jj commits can be freely modified. This enables a high-quality commit workflow: - -1. Before starting work, run `jj st`. If `@` already has changes, run `jj new` first. If `@` is empty, use it as-is. -2. Describe your intended changes with `jj desc -m "Message"` -3. Make your changes. -4. Do NOT run `jj new` when finished — leave that to the next task's step 1. - -You may refine the commit using `jj squash` or `jj absorb` as needed - -### Change IDs vs Commit IDs - -- **Change ID**: A stable identifier (like `tqpwlqmp`) that persists when a commit is rewritten -- **Commit ID**: A content hash (like `3ccf7581`) that changes when commit content changes - -Prefer using Change IDs when referencing commits in commands. - -## Essential Workflow - -### Starting Work: Describe First, Then Code - -**Always create your commit message before writing code:** +`@` empty? reuse. `@` has work to preserve? `jj new` first. then: ```bash -# First, describe what you intend to do -jj desc -m "feat: Add user authentication to login endpoint" - -# Then make your changes - they automatically become part of this commit -# ... edit files ... - -# Check status +jj desc -m "Add login validation" +# edit files jj st ``` -For the full starting-a-change workflow (when to reuse `@` vs `jj new`, anti-patterns, decision logic), see `references/NEW_CHANGE.md`. - -For unrelated or sibling work that should branch from `trunk()`, see `references/NONLINEAR.md`. - -### Creating Atomic Commits +never run `jj new` at task end. next task decides reuse/new. full branch logic: [`references/NEW_CHANGE.md`](references/NEW_CHANGE.md). work belongs on `trunk()` sibling? [`references/NONLINEAR.md`](references/NONLINEAR.md). -Each commit should represent ONE logical change. +## inspect narrowly -### Viewing History +agent inspection defaults to compact commands in [`references/TEMPLATES.md`](references/TEMPLATES.md), all with `jj --no-pager`. widen revset/fileset before requesting large patches. ```bash -# View recent commits jj log - -# View with patches jj log -p - -# View specific commit jj show - -# View diff of working copy jj diff ``` -If you need to run `jj log`, `jj show`, or `jj diff` as an agent, use the matching compact command from `references/TEMPLATES.md` unless the full default output is explicitly needed. +need query grammar? [`references/QUERY_LANGUAGES.md`](references/QUERY_LANGUAGES.md). -For the revsets, filesets, and template syntax behind those compact commands, see `references/QUERY_LANGUAGES.md`. - -### Moving Between Commits +move: ```bash -# Create a new empty commit on top of current jj new - -# Create new commit with message -jj new && jj desc -m "Commit message" - -# Edit an existing commit (working copy becomes that commit) +jj new && jj desc -m "Describe next change" jj edit - -# Edit the previous commit jj prev -e - -# Edit the next commit jj next -e ``` -## Refining Commits - -If you need to refine a commit (squash, abandon, undo, split, etc), see [Refining commits](references/REFINE_COMMIT.md) +## refine -## Working with Bookmarks (Branches) +squash, restore, absorb, abandon, split alternative? [`references/REFINE_COMMIT.md`](references/REFINE_COMMIT.md). review `jj show @` or `jj diff`; ensure atomic; remove unrelated edits or move them correctly. then `jj st`. -Bookmarks are jj's equivalent to git branches: +bookmarks are branches but do not auto-advance: ```bash -# Create a bookmark at current commit jj bookmark create my-feature -r@ - -# Move bookmark to a different commit jj bookmark move my-feature --to - -# List bookmarks jj bookmark list - -# Delete a bookmark jj bookmark delete my-feature ``` -If you need to run `jj bookmark list`, use the matching compact command from `references/TEMPLATES.md`. +push only when explicitly requested; see [`references/PUSH.md`](references/PUSH.md) and [`references/REMOTES.md`](references/REMOTES.md). - -## Parallel Workspaces +## workspaces -For running multiple agents in parallel against the same repo without working-copy collisions, use `jj workspace`. Each workspace gets its own `@` while sharing the underlying repo store. +parallel agents touching same repo? isolate working copies: ```bash -# Quick reference (full convention in references/WORKSPACES.md) -jj workspace add .workspaces/- # Create -jj workspace list # List -jj workspace forget # Untrack (files stay on disk) +jj workspace add .workspaces/- +jj workspace list +jj workspace forget ``` -If you need to run `jj workspace list`, use the matching compact command from `references/TEMPLATES.md`. - -See `references/WORKSPACES.md` for the full convention: the `.workspaces/` directory layout, `.gitignore` safety check, naming, environment bootstrapping, agent handoff, monitoring, stale-workspace recovery, and merging results from multiple workspaces back together. +shared store/op log, separate `@`. `.gitignore` gate, directory priority, bootstrap, handoff, integration choice, stale recovery all mandatory: [`references/WORKSPACES.md`](references/WORKSPACES.md). -## Working with tags +## co-located git -jujutsu does not yet support tags and pushing them to a remote. If you need to tag (such as for a release), you will need to use git to create and push the tags. - -## Git Integration (Co-located Repos) - -Always use co-located repos when working with existing git projects. They give you jj locally while keeping the repo remote-compatible with git tooling. +existing git project? prefer co-location: ```bash -jj git clone --colocate # Clone a git repo -jj git init --colocate # Adopt an existing git repo +jj git clone --colocate +jj git init --colocate ``` -See `references/COLOCATED.md` for the complete workflow: the mutation rule (`git` is forbidden for mutations, allowed read-only), the git-command allowlist, common gotchas, and switching modes when absolutely necessary. - -See `references/GOTCHAS.md` when the behavior feels surprising and you want the short list of jj-specific footguns before trying a git-style workaround. +need tags? jj cannot yet create and push tags; carefully switch to git mode only when required. all co-location safety: [`references/COLOCATED.md`](references/COLOCATED.md). -### Pushing Changes +## conflicts -For pushing bookmarks to a remote, see `references/PUSH.md`. For named remotes, fork+upstream setups, and other multi-remote workflows, see `references/REMOTES.md`. - -## Handling Conflicts - -jj treats conflicts as first-class objects — a commit can contain a conflict, and that conflict persists through rebases until resolved. `jj` refuses to push conflicted commits, so they must be resolved before `jj git push`. +rebase/squash can succeed with conflicted commit. conflict persists; push blocked until resolved. ```bash -jj st # Reports if @ has unresolved conflicts -jj resolve --list # Lists conflicted paths -jj resolve --tool :ours # Take side #1 non-interactively (agent-safe) -jj resolve --tool :theirs # Take side #2 non-interactively (agent-safe) +jj st +jj resolve --list +jj resolve --tool :ours +jj resolve --tool :theirs ``` -**Never run bare `jj resolve` (no `--tool`)** — it's interactive and will hang in non-interactive agent environments. Either pass `--tool :ours` / `--tool :theirs`, or edit conflict markers directly in the file and let `jj st` snapshot the resolution. +bare `jj resolve`? never in agent. choose side with explicit tool or edit markers directly. then status, marker grep, project checks. repeated descendant conflict? resolve first conflicted ancestor. full playbook: [`references/CONFLICTS.md`](references/CONFLICTS.md). -See `references/CONFLICTS.md` for the full resolution playbook: marker formats (diff vs snapshot), five resolution paths, ancestor-level resolution to avoid re-resolving across descendants, verification (beyond `jj st`), and anti-patterns. +## recovery - -## Recovery and the Operation Log - -The op log records every mutation. Nothing is ever lost. +op log records mutations. work recoverable. ```bash -jj undo # Reverse the last operation (primary recovery tool) -jj op log # See all operations -jj op restore # Jump back to any past state -jj evolog -r # See how a specific change evolved +jj undo +jj op log +jj op restore +jj evolog -r ``` -If you need to run `jj op log` or `jj evolog`, use the matching compact commands from `references/TEMPLATES.md` first. Add `-p` only after you have narrowed the scope. - -**Always reach for `jj undo` first** when something looks wrong — it's always correct and safe. See `references/RECOVERY.md` for recovery patterns by scenario (bad squash, accidental abandon, lost work, etc.). - -## Preserving Commit Quality - -**IMPORTANT**: Because commits are mutable, always refine them: - -1. **Review your commit**: `jj show @` or `jj diff` -2. **Is it atomic?** One logical change per commit -3. **Is the message clear?** Use imperative verb phrase in sentence case format with no full stop: "Verb object" -4. **Are there unrelated changes?** Use `jj restore` to move changes out, then create separate commits -5. **Should changes be elsewhere?** Use `jj squash` or `jj absorb` - -## Quick Reference - -| Action | Command | -|--------|---------| -| Describe commit | `jj desc -m "message"` | -| View status | `jj st` | -| View log | `jj log` | -| View diff | `jj diff` | -| New commit | `jj st` then `jj new` only if `@` has changes, then `jj desc -m "message"` | -| Edit commit | `jj edit ` | -| Squash to parent | `jj squash --into @- -m "message"` | -| Auto-distribute | `jj absorb` | -| Abandon commit | `jj abandon ` | -| Undo last operation | `jj undo` | -| Restore files | `jj restore [paths]` | -| Create bookmark | `jj bookmark create ` | -| Push bookmark | `jj git push -b ` | -| Add workspace | `jj workspace add .workspaces/-` | -| List workspaces | `jj workspace list` | -| Forget workspace | `jj workspace forget ` | -| See operation log | `jj op log` | -| Jump to past state | `jj op restore ` | -| See change evolution | `jj evolog -r ` | - -## Best Practices Summary - -1. **Describe first**: Set the commit message before coding -2. **One change per commit**: Keep commits atomic and focused -3. **Use change IDs**: They're stable across rewrites -4. **Refine commits**: Leverage mutability for clean history -5. **Embrace the workflow**: No staging area, no stashing — the op log replaces both -6. **Workspaces for parallel agents**: Isolate concurrent agent work in `.workspaces/-` (see `references/WORKSPACES.md`) -7. **`jj undo` first**: When something looks wrong, undo before fixing manually (see `references/RECOVERY.md`) +something wrong? `jj undo` first, not manual reversal. need older state? compact op inspection first; patches only after narrowing. scenarios: [`references/RECOVERY.md`](references/RECOVERY.md). + +## provenance + +fork: [danverbraganza](https://skills.sh/danverbraganza/jujutsu-skill/jujutsu). mutation gate: [knoopx](https://skills.sh/knoopx/pi/jujutsu). agent workspaces: [onevcat](https://skills.sh/onevcat/skills/onevcat-jj). local workspace path: [edmundmiller](https://lobehub.com/skills/edmundmiller-dotfiles-using-jj-workspaces). recovery framing: [trevors](https://skills.sh/trevors/dot-claude/jj-workflow). queries, nonlinear work, handoff: [joshuadavidthomas](https://github.com/joshuadavidthomas/agent-skills/tree/main/jj). diff --git a/modules/programs/tui/pi/skills/jujutsu/references/COLOCATED.md b/modules/programs/tui/pi/skills/jujutsu/references/COLOCATED.md index 3e8b0cb..19022fa 100644 --- a/modules/programs/tui/pi/skills/jujutsu/references/COLOCATED.md +++ b/modules/programs/tui/pi/skills/jujutsu/references/COLOCATED.md @@ -1,81 +1,58 @@ -# Co-located jj + git Repositories +# co-located jj + git -A **co-located** repo has both `.jj/` and `.git/` at the same root. jj manages local operations; git stays in sync underneath so remote-side tooling (CI, GitHub, hooks, IDE plugins, `gh` CLI) continues to work normally. - -This is the **strongly recommended** setup for working with an existing git project. - -## Why co-located - -- **Local: jj's superior model.** Mutable commits, no staging area, the op log as a safety net. -- **Remote: still git.** GitHub sees ordinary commits and refs. Collaborators don't need to know you use jj. -- **Tooling parity.** IDE git integrations, pre-commit hooks, `gh`/`git` CLI for read-only inspection all continue to work. - -## Creating a co-located repo +co-located root has `.jj/` and `.git/`. jj owns local state; git compatibility supports GitHub, CI, hooks, IDE, `gh`. existing git project? strongly prefer this shape. ```bash -# From scratch jj git init --colocate - -# From a remote jj git clone --colocate - -# Adopt an existing git repo (run from inside it) cd existing-git-repo jj git init --colocate ``` -After this, both `.jj/` and `.git/` exist and stay synchronized automatically. **Never run `jj git init` without `--colocate`** on a project you already have git history for — non-colocated init creates a separate git store inside `.jj/repo/store/git` which is harder to work with. +existing git history? never omit `--colocate`; otherwise separate store appears under `.jj/repo/store/git`. -## The mutation rule +## mutation rule -> **Never use `git` for mutations in a co-located jj repo.** Read-only `git` is fine. +git may inspect only: -| git command | Allowed in jj repo? | +| command | decision | |---|---| -| `git log`, `git show`, `git diff`, `git blame`, `git grep` | ✅ Allowed (jj equivalents preferred) | -| `git status` | ✅ Allowed (shows git's view; may differ from `jj st`) | -| `git commit`, `git add`, `git stash`, `git reset` | ❌ Forbidden — corrupts jj state | -| `git checkout `, `git switch` | ❌ Forbidden — use `jj edit` instead | -| `git rebase`, `git merge`, `git cherry-pick` | ❌ Forbidden — use `jj rebase`, `jj new `, `jj duplicate` | -| `git fetch` | ⚠️ Use `jj git fetch` — it keeps jj in sync | -| `git pull` | ❌ Forbidden — `git pull` does fetch+merge; use `jj git fetch` + `jj rebase` | -| `git push` | ❌ Forbidden — use `jj git push -b ` | +| `git log`, `git show`, `git diff`, `git blame`, `git grep`, `git status` | safe read-only; jj equivalent preferred | +| `git commit`, `git add`, `git stash`, `git reset` | forbidden | +| `git checkout `, `git switch` | forbidden; `jj edit` | +| `git rebase`, `git merge`, `git cherry-pick` | forbidden; `jj rebase`, `jj new `, `jj duplicate` | +| `git fetch` | use `jj git fetch` | +| `git pull` | forbidden; `jj git fetch` then `jj rebase` | +| `git push` | forbidden; `jj git push -b ` | -The reason: jj snapshots the working copy on every jj command. If git mutates state behind jj's back, jj's next snapshot will be confused about what changed when, and the op log can get out of sync. +why? jj snapshots working copy. hidden git mutation breaks jj's state/op-log model. -## Switching to git mode (rare; usually a smell) +## forced git-only operation -If you genuinely need to use a git workflow for one operation (e.g., an external tool insists), do it carefully: +external tool truly requires mutation? last resort: ```bash -# 1. Ensure jj working copy is committed and clean jj st -# (resolve anything pending — describe, refine, etc.) - -# 2. Now run the git operation +# resolve and finish pending jj state git - -# 3. Return to jj — jj will re-sync on the next command -jj st # Triggers re-sync -jj edit # Resume work +jj st +jj edit ``` -**Almost every git operation has a jj equivalent that's safer.** Reach for git mode only as a last resort. - -## Common gotchas +almost always safer jj equivalent exists. -- **Git complains about uncommitted changes**: jj's working copy is always a commit; git sees that as "uncommitted." Use `jj st` (not `git status`) to assess state. -- **HEAD detachment**: jj manages `HEAD` per change. `git checkout` will detach HEAD in confusing ways — use `jj edit` instead. -- **`.gitignore` is respected by jj** automatically. `.jjignore` is only needed if you want jj-only ignore patterns the outer git doesn't see. -- **Branches vs bookmarks**: git branches become jj bookmarks on fetch. Bookmarks don't auto-advance like git branches — you must `jj bookmark move` before pushing. +## surprises -## Pushing from a co-located repo +- git says uncommitted? normal view of jj working-copy commit. trust `jj st`. +- detached `HEAD`? jj manages it. never `git checkout`; use `jj edit`. +- `.gitignore` automatically respected. `.jjignore` only for jj-only patterns. +- fetched git branches become bookmarks. bookmarks do not auto-advance. -Use `jj git push`, not `git push`: +push: ```bash -jj bookmark move main --to @ # Move bookmark to your latest change -jj git push -b main # Push to remote +jj bookmark move main --to @ +jj git push -b main ``` -See `references/PUSH.md` for the full push workflow. +full push gate: [`PUSH.md`](PUSH.md). diff --git a/modules/programs/tui/pi/skills/jujutsu/references/COMMIT_MSG.md b/modules/programs/tui/pi/skills/jujutsu/references/COMMIT_MSG.md deleted file mode 100644 index 829c84c..0000000 --- a/modules/programs/tui/pi/skills/jujutsu/references/COMMIT_MSG.md +++ /dev/null @@ -1,26 +0,0 @@ -# Creating good commit messages - -1. Use the following format: - -```text -: - - -``` - -The valid values are: fix, feat, chore, docs -Type and subject are required -Body is optional - -2. If there is a body, separate it from the subject with a blank line -3. Limit the subject line to 50 characters. This is not a hard limit but a rule of thumb. The subject line should explain the "what" of the logical change -4. Capitalize the subject line -5. Do not end the subject line with a period -6. Use the imperative mood in the subject line - Imperative mood just means “spoken or written as if giving a command or instruction”. A few examples: - - * Clean your room - * Close the door - * Take out the trash -7. Wrap the body at 72 characters -8. Use the body to explain what and why vs. how diff --git a/modules/programs/tui/pi/skills/jujutsu/references/CONFLICTS.md b/modules/programs/tui/pi/skills/jujutsu/references/CONFLICTS.md index 326e0e3..61d8ca2 100644 --- a/modules/programs/tui/pi/skills/jujutsu/references/CONFLICTS.md +++ b/modules/programs/tui/pi/skills/jujutsu/references/CONFLICTS.md @@ -1,37 +1,20 @@ -# Resolving Conflicts +# conflicts -jj treats conflicts as **first-class objects**: a commit can contain a conflict, and that conflict **persists through rebases** until someone resolves it. This is the headline mental-model difference from git, where a working tree must be conflict-free before committing. +jj conflict is commit data. rebase/squash producing conflict succeeds; commit stays marked. further rebase allowed. push rejects conflicted history. -For an agent, this changes the rhythm: - -- A `jj rebase` or `jj squash` that produces a conflict **does not fail**. It succeeds; the resulting commit is just marked conflicted. -- You can keep working — even keep rebasing the conflicted commit further — and resolve it later. -- `jj` won't let you push a conflicted commit to a remote, so conflicts must be resolved before `jj git push`. - -## Detecting conflicts - -```bash -jj st # Shows "There are unresolved conflicts" if any -jj resolve --list # Lists all conflicted paths in @ -jj resolve --list -r # Lists conflicts in a specific change -jj log # Conflicted changes are shown with a "conflict" marker -``` - -## Conflict marker formats - -jj supports three marker styles (set via `ui.conflict-marker-style`): - -- **`diff`** (modern default) — shows base→side as a diff -- **`snapshot`** — full content of each side, like git's `<<<<<<<` style -- **`git`** — legacy git-compatible 3-way - -Check your style: +## inspect ```bash +jj st +jj resolve --list +jj resolve --list -r +jj log jj config get ui.conflict-marker-style ``` -### Example: `diff` style +styles: `diff` modern default, `snapshot` full sides/base, `git` legacy 3-way. + +`diff`: ```text <<<<<<< Conflict 1 of 1 @@ -43,11 +26,7 @@ side 2 content here >>>>>>> Conflict 1 of 1 ends ``` -- Side #1 = "ours" (the destination — typically your current branch/change) -- Side #2 = "theirs" (the source — typically what's being rebased/merged in) -- The `%%%%%%%` block shows what side #1 changed *from the common base*; side #2's content is shown directly. - -### Example: `snapshot` style +`snapshot`: ```text <<<<<<< Conflict 1 of 1 @@ -60,117 +39,69 @@ side 2 content here >>>>>>> Conflict 1 of 1 ends ``` -Both styles delimit conflict regions identically. To resolve: replace the entire `<<<<<<< ... >>>>>>>` block with the desired final content. +side #1 = ours/destination, usually current line. side #2 = theirs/source, usually incoming/rebased line. resolve manual by replacing whole marker block with final content. -## Five resolution paths (agent-friendly) +## choose path -`jj resolve` with no `--tool` launches an interactive merge tool and **will hang in non-interactive agent environments**. Use one of these instead: +bare `jj resolve` launches interactive merge tool. agent? never. -### 1. Edit conflict markers directly (most common) - -Read the file, replace each `<<<<<<<` block with the resolved content, save. Then snapshot: +1. complex merge: edit markers directly, then `jj st`. +2. one side wholly correct: ```bash -jj st # Triggers snapshot; should report no remaining conflicts -``` - -This is the canonical agent path. Works for any merge complexity. - -### 2. Take one side wholesale: `:ours` / `:theirs` - -For conflicts where one side simply wins (e.g., a rebase brings in unrelated formatting changes you don't want): - -```bash -jj resolve --tool :ours # Keep side #1; drop side #2's conflicting changes -jj resolve --tool :theirs # Keep side #2; drop side #1's conflicting changes - -# Scope to specific paths +jj resolve --tool :ours +jj resolve --tool :theirs jj resolve --tool :ours path/to/file.rs ``` -These built-in tools are **non-interactive** and safe to use in agent contexts. They apply to all conflicts in `@` (or the paths given). - -### 3. Restore from a specific version: `jj restore --from` - -When neither side is right but a *different* revision has the content you want: +3. another revision correct: ```bash jj restore --from path/to/file.txt ``` -This pulls the file contents from `` into the working copy, replacing conflict markers entirely. - -### 4. Abandon a hopelessly conflicted change - -If the conflicted change wasn't worth keeping: +4. change not worth keeping: ```bash jj abandon ``` -Descendants are rebased onto the parent. Their own conflicts (if any) remain to be resolved separately. - -### 5. Resolve at the ancestor, let jj re-propagate +descendants rebase; their conflicts remain. -If a rebase produced the same conflict in many descendants, **don't resolve each descendant individually**. Resolve once at the change where the conflict first appeared, and jj will re-propagate the resolution forward: +5. same conflict repeated in descendants? resolve earliest conflicted ancestor once: ```bash -# Find where the conflict first appeared jj log -r 'conflicts()' - -# Edit that change directly jj edit -# ... fix conflict markers ... -jj st # Snapshot the resolution -jj edit @- # Move back to where you were +# edit markers +jj st +jj edit ``` -Descendants pick up the resolution automatically. +jj re-propagates fix. record original ID before moving; never assume `@-` returns prior location. -## Verifying a resolution +## verify -After editing, **don't trust `jj st` alone**: +status alone insufficient: ```bash -# 1. Status should report no conflicts jj st - -# 2. Grep for residual markers (catches typos that left markers in place) git grep -E '^(<{7}|>{7}|\\%{7}|\\+{7})' || echo 'no residual conflict markers' - -# 3. Run the project's tests/linter — markers may be syntactically valid in some -# languages (e.g. inside strings) and parse-tests catch what eyeballing misses. -``` - -In a colocated repo, `git grep` is allowed (read-only). In a non-colocated repo, use `grep -rE` or `rg`. - -## Pushing conflicted commits is blocked - -```bash -jj git push -b main -# Refused: branch main contains conflicts +# run project tests/linter ``` -You'll need to resolve before pushing. There's no `--force-push-conflicts` option — this is by design. - -## Anti-patterns +co-located? read-only `git grep` safe. non-colocated? `rg` or `grep -rE`. tests catch markers valid inside language strings. -- ❌ **`jj resolve` (no `--tool`)** — interactive; will hang the agent. Always pass `--tool :ours` / `--tool :theirs` or edit markers manually. -- ❌ **Resolving descendants individually after a rebase** — wasteful and error-prone; resolve at the ancestor (path 5). -- ❌ **Relying on `jj st` to verify resolution** — also grep for residual markers and run tests. -- ❌ **Trying to `git checkout` to "drop" a conflict** in a colocated repo — corrupts jj state. Use `jj abandon` or resolve. -- ❌ **`jj squash` to "hide" a conflict into another commit** — the conflict propagates; it doesn't disappear. +push still refuses conflict; no force-conflicts option. -## Quick reference +avoid descendant-by-descendant fixes, `git checkout`, squash-to-hide, and bare resolve. -| Action | Command | +| need | command | |---|---| -| List conflicts in `@` | `jj resolve --list` | -| List conflicts everywhere | `jj log -r 'conflicts()'` | -| Resolve manually | Edit file, then `jj st` | -| Take "ours" (side #1) | `jj resolve --tool :ours [paths...]` | -| Take "theirs" (side #2) | `jj resolve --tool :theirs [paths...]` | -| Restore from another rev | `jj restore --from ` | -| Drop the change | `jj abandon ` | -| Find conflict's ancestor | `jj log -r 'conflicts() ~ ::conflicts()-'` | -| Check marker style | `jj config get ui.conflict-marker-style` | +| current paths | `jj resolve --list` | +| all conflicted changes | `jj log -r 'conflicts()'` | +| manual | edit, then `jj st` | +| side #1/#2 | `jj resolve --tool :ours [paths...]` / `:theirs` | +| another rev | `jj restore --from ` | +| drop change | `jj abandon ` | +| first conflict | `jj log -r 'conflicts() ~ ::conflicts()-'` | diff --git a/modules/programs/tui/pi/skills/jujutsu/references/GOTCHAS.md b/modules/programs/tui/pi/skills/jujutsu/references/GOTCHAS.md index 5b18171..2a669c2 100644 --- a/modules/programs/tui/pi/skills/jujutsu/references/GOTCHAS.md +++ b/modules/programs/tui/pi/skills/jujutsu/references/GOTCHAS.md @@ -1,47 +1,16 @@ -# Gotchas - -Short list of jj behaviors that regularly surprise agents. - -**Tested with jj 0.41.0** - -## 1. Working Copy Is a Commit - -`@` is always a commit, not a staging area. `jj new` starts a different change; it does not finish the current one. - -## 2. Most jj Commands Snapshot the Working Copy - -Running `jj st`, `jj log`, and many other commands can record filesystem changes into the working-copy commit. If you intentionally need a stale view, use `--ignore-working-copy`. - -## 3. Change IDs and Commit IDs Are Different - -Change IDs are stable across rewrites. Commit IDs change whenever content or metadata changes. Prefer change IDs when handing work to another agent. - -## 4. `jj undo` Is the First Recovery Tool - -Do not manually reverse a bad `rebase`, `squash`, or `abandon` before trying `jj undo`. Use `references/RECOVERY.md` for deeper recovery. - -## 5. Pager Output Is Not a Good Agent Default - -Use the compact commands in `references/TEMPLATES.md`. Those commands intentionally use `jj --no-pager ...`. - -## 6. Co-located Repos Still Forbid Git Mutations - -`git log`, `git show`, `git diff`, `git blame`, `git grep`, and `git status` are fine. `git commit`, `git add`, `git rebase`, `git push`, and similar mutations can corrupt jj state. - -## 7. `jj workspace forget` Does Not Delete Files - -It only unregisters the workspace. Delete the directory separately if cleanup is intended. - -## 8. Stale Workspaces Are Normal in Parallel Work - -If another workspace rewrites your base, use `jj workspace update-stale`. Verify the result with `jj st` instead of improvising a manual repair. - -## 9. Bare `jj resolve` Is Interactive - -For agent-safe conflict handling, use `jj resolve --tool :ours`, `jj resolve --tool :theirs`, or edit conflict markers directly. - -## 10. Default Output Is Often Too Large - -Prefer compact templates, targeted revsets, and narrow filesets before reaching for full `jj log -p` or `jj show`. - -When behavior feels surprising, stop and check `references/NEW_CHANGE.md`, `references/TEMPLATES.md`, `references/WORKSPACES.md`, or `references/RECOVERY.md` before inventing a git-style workaround. +# gotchas + +assume jj 0.41.0. + +- `@` is commit, not staging. `jj new` starts next change; does not finish current. +- most commands, including `jj st` and `jj log`, may snapshot filesystem. stale view intentionally needed? `--ignore-working-copy`. +- change ID stable across rewrites; commit ID changes. handoff uses change ID. +- bad rebase/squash/abandon? `jj undo` before manual repair. see [`RECOVERY.md`](RECOVERY.md). +- pager/default output too large? compact `jj --no-pager` commands from [`TEMPLATES.md`](TEMPLATES.md). +- co-located still forbids git mutation. only `git log`, `show`, `diff`, `blame`, `grep`, `status` safe. +- `jj workspace forget` unregisters only; files remain. +- stale parallel workspace? `jj workspace update-stale`, then `jj st`. +- bare `jj resolve` interactive. use `--tool :ours`, `--tool :theirs`, or edit markers. +- inspection too broad? targeted revset/fileset before `jj log -p` or full show. + +surprise remains? inspect [`NEW_CHANGE.md`](NEW_CHANGE.md), [`TEMPLATES.md`](TEMPLATES.md), [`WORKSPACES.md`](WORKSPACES.md), [`RECOVERY.md`](RECOVERY.md). never invent git-style workaround. diff --git a/modules/programs/tui/pi/skills/jujutsu/references/NEW_CHANGE.md b/modules/programs/tui/pi/skills/jujutsu/references/NEW_CHANGE.md index 7212d8f..793713e 100644 --- a/modules/programs/tui/pi/skills/jujutsu/references/NEW_CHANGE.md +++ b/modules/programs/tui/pi/skills/jujutsu/references/NEW_CHANGE.md @@ -1,52 +1,30 @@ -# Starting a New Change +# start change -The jj workflow is: **describe first, then code, then refine**. The working copy is always a commit (`@`), so you're already in one when you start. The question is whether to reuse it or start fresh. - -## The opening sequence +rule: describe first, edit, refine. `@` already commit. ```bash -# 1. Check what @ currently looks like jj st ``` -**If `@` is empty** (no changes, no description set, or description is fine to discard): - -- Reuse it. Just describe and start. - -**If `@` has changes you want to keep** (it's someone else's WIP, or work you haven't finished): +`@` empty and description absent/discardable? reuse. `@` contains work to preserve? run `jj new`; creates empty child. -- Start fresh with `jj new` — this creates a new empty commit on top of `@`. +then, before file edit: ```bash -# 2. Describe before coding (only with -m; never editor-based) -jj desc -m "feat: Add user authentication to login endpoint" - -# 3. Make changes — they snapshot to @ automatically on the next jj command -# (no `jj add`, no `jj commit` needed) - -# 4. Verify +jj desc -m "Add login validation" +# edit; next jj command snapshots jj st ``` -## Why describe first - -Setting the message up front: - -- Forces you to articulate the change as one logical unit before writing code (atomic commits) -- Means there's never a phase where `@` says "(no description set)" -- Makes the change navigable in `jj log` while it's still being built - -See `references/COMMIT_MSG.md` for the message format conventions. - -## After the change is done +one description should name one logical change. inline `-m` mandatory for agent; editor prompt hangs. no `jj add`, no `jj commit`. -**Do NOT run `jj new` to "close" the change.** In jj, the working copy is always a commit — there's no separate commit step. Leave `@` as-is; the *next* task's step 1 (`jj st` → reuse or `jj new`) handles transition. +done? leave `@` there. do not `jj new` to close. next task performs same status decision. -If refinement is needed (split, squash, absorb, abandon), see `references/REFINE_COMMIT.md`. +need split/squash/absorb/abandon? [`REFINE_COMMIT.md`](REFINE_COMMIT.md). unrelated sibling? [`NONLINEAR.md`](NONLINEAR.md). -## Anti-patterns +avoid: -- ❌ `jj commit` — doesn't exist; the working copy is already a commit -- ❌ `jj desc` without `-m` — opens an editor; will hang in non-interactive agent environments -- ❌ Running `jj new` at the end of a task — leaves an empty `@` for the next agent to clean up -- ❌ Starting code before describing — you'll forget to describe, or describe vaguely after the fact +- code before description. +- bare `jj desc`. +- `jj commit` mental model. +- end-of-task `jj new` leaving empty `@`. diff --git a/modules/programs/tui/pi/skills/jujutsu/references/NONLINEAR.md b/modules/programs/tui/pi/skills/jujutsu/references/NONLINEAR.md index aa559a3..68115e7 100644 --- a/modules/programs/tui/pi/skills/jujutsu/references/NONLINEAR.md +++ b/modules/programs/tui/pi/skills/jujutsu/references/NONLINEAR.md @@ -1,65 +1,29 @@ -# Nonlinear Work +# nonlinear work -This skill supports sibling commits and unrelated work. Do not force everything onto the current stack if the work is logically independent. +assume jj 0.41.0. new work unrelated to current stack? sibling from `trunk()`, not forced child. -**Tested with jj 0.41.0** - -## When to Start a Sibling from `trunk()` - -Use a fresh sibling when: - -- `@` already represents one logical change and the new work is unrelated -- the user wants multiple independent lines of work -- you need to compare or merge two alternative implementations -- a quick fix appears while a feature change is already in progress - -## Preferred Flow - -This skill keeps the local "describe first" rule, even for sibling work: +sibling fits when current `@` already logical change, independent lines requested, alternatives compared/merged, or quick fix interrupts feature. ```bash jj st jj new trunk() -jj desc -m "fix: handle stale workspace recovery" -# make changes +jj desc -m "Handle stale workspace recovery" +# edit jj st ``` -Use `trunk()` instead of guessing `main` or `master`. If the new work should build on the current change, use plain `jj new` instead of `jj new trunk()`. - -## Child vs Sibling +use `trunk()`, never guess `main`/`master`. -Use a child (`jj new`) when: +child `jj new` when work depends on current, stack requested, or intentional follow-up. sibling `jj new trunk()` when review/land/abandon should be independent or parallel agents need separate history. -- the new work depends on the current change -- the user wants a stacked sequence -- the current commit is intentionally being split into follow-up commits - -Use a sibling from `trunk()` when: - -- the work should review, land, or be abandoned independently -- you are branching off to do an unrelated fix, doc change, or experiment -- parallel agents need clearly separated lines of history - -## Merge-Shaped Work - -If two independently meaningful lines of work should remain visible as a merge, create an explicit merge commit: +both lines should remain visible? explicit merge: ```bash -jj new -m "merge: combine related lines of work" +jj new -m "Combine related work" ``` -Ask the user before choosing between: - -- rebasing one line onto the other -- keeping a visible merge -- pushing each line separately - -## Anti-Patterns +rebase one onto other, visible merge, or separate pushes? consequential choice; ask user. -- Do not keep piling unrelated work into the current `@` just because it is convenient. -- Do not adopt a `describe -> code -> jj new -> repeat` loop. In this skill, `jj new` starts the next change; it does not close the current one. -- Do not default to `jj new trunk() --no-edit -m ...` here. Keep the local sequence: choose the base first, then run `jj desc -m ...`. -- Do not hardcode `main` or `master` when `trunk()` expresses the intent. +never pile unrelated work into `@`. never use describe/edit/`jj new` as close-and-repeat loop. base first, then separate `jj desc -m`; do not default to `jj new trunk() --no-edit -m ...` here. -See `references/NEW_CHANGE.md` for the default change-starting workflow and `references/WORKSPACES.md` for multi-workspace parallelism. +change start: [`NEW_CHANGE.md`](NEW_CHANGE.md). parallel copies: [`WORKSPACES.md`](WORKSPACES.md). diff --git a/modules/programs/tui/pi/skills/jujutsu/references/PUSH.md b/modules/programs/tui/pi/skills/jujutsu/references/PUSH.md index 07b06fe..906122a 100644 --- a/modules/programs/tui/pi/skills/jujutsu/references/PUSH.md +++ b/modules/programs/tui/pi/skills/jujutsu/references/PUSH.md @@ -1,39 +1,27 @@ -### Pushing Changes +# push -When the user asks you to push changes: +push only after explicit user request. -```bash -# Push a specific bookmark to the remote -jj git push -b - -# Example: push the main bookmark -jj git push -b main -``` +before push: correct bookmark target? commits atomic/refined? no conflicts? bookmark does not auto-advance. -**Before pushing, ensure:** - -1. Your bookmark points to the correct commit (bookmarks don't auto-advance like git branches) -2. The commits are refined and atomic -3. The user has explicitly requested the push - -**IMPORTANT**: Unlike git branches, jj bookmarks do not automatically move when you create new commits. You must manually update them before pushing: +existing bookmark: ```bash -# Move an existing bookmark to the current commit jj bookmark move my-feature --to @ - -# Then push it jj git push -b my-feature ``` -If no bookmark exists for your changes, create one first: +no bookmark: ```bash -# Create a bookmark at the current commit jj bookmark create my-feature - -# Then push it jj git push -b my-feature ``` -For named remotes, multi-remote setups (e.g. fork + upstream), tracking remote bookmarks, and one-time configuration for the two canonical multi-remote workflows, see `references/REMOTES.md`. +specific example: + +```bash +jj git push -b main +``` + +multiple/named remotes, tracking, fork/upstream config? [`REMOTES.md`](REMOTES.md). diff --git a/modules/programs/tui/pi/skills/jujutsu/references/QUERY_LANGUAGES.md b/modules/programs/tui/pi/skills/jujutsu/references/QUERY_LANGUAGES.md index e014493..526e2eb 100644 --- a/modules/programs/tui/pi/skills/jujutsu/references/QUERY_LANGUAGES.md +++ b/modules/programs/tui/pi/skills/jujutsu/references/QUERY_LANGUAGES.md @@ -1,91 +1,51 @@ -# Query Languages +# query languages -Use jj's query languages when you need to select revisions, paths, or render compact output without falling back to the default verbose UI. +assume jj 0.41.0. need narrow revisions, paths, output? use queries; avoid verbose default. -**Tested with jj 0.41.0** +## revsets -## Revsets - -Use revsets to select commits and workspaces. - -Common selectors: - -- `@`: current working-copy change -- `@-`: parent of the current working-copy change -- `trunk()`: configured mainline; use this instead of guessing `main` vs `master` -- `::@`: all ancestors of `@` -- `trunk()..@`: work reachable from `@` that is not on `trunk()` -- `working_copies()`: all workspace working-copy commits -- `@`: another workspace's working-copy commit -- ``: a stable change ID such as `wqzktpqm` - -Agent patterns: +- `@`: current working-copy change. +- `@-`: parent. +- `trunk()`: configured mainline; no `main`/`master` guess. +- `::@`: ancestors of `@`. +- `trunk()..@`: current reachable work off trunk. +- `working_copies()`: all workspace tips. +- `@`: named workspace tip. +- ``: stable ID. ```bash -# Current work relative to trunk jj --no-pager log -r 'trunk()..@' - -# All active workspace tips jj --no-pager log -r 'working_copies()' - -# One specific workspace tip jj --no-pager log -r '@' ``` -Quote revsets that contain punctuation or function calls. - -## Filesets - -Use filesets when a command should operate on only part of the tree. +punctuation/function present? shell-quote. -Common patterns: +## filesets -- `path` or `"path"`: cwd-relative path prefix -- `file:"path"`: exact cwd-relative file path -- `glob:"pattern"`: cwd-relative glob -- `root:"path"`: workspace-relative path prefix -- `~x`: everything except `x` -- `x & y`: intersection -- `x | y`: union -- `x ~ y`: subtract `y` from `x` - -Examples: +- `path` / `"path"`: cwd-relative prefix. +- `file:"path"`: exact cwd-relative file. +- `glob:"pattern"`: cwd-relative glob. +- `root:"path"`: workspace-relative prefix. +- `~x`: except x. +- `x & y`: intersection. +- `x | y`: union. +- `x ~ y`: subtraction. ```bash -# Only markdown files in the current directory jj diff 'glob:"*.md"' - -# Everything in src except snapshots jj diff 'src ~ glob:"src/**/*.snap"' - -# Exact file path jj diff 'file:"README.md"' ``` -## Templates - -Use templates when default output is too large or too decorative for agent work. +## templates -Common building blocks: - -- `++`: concatenate output pieces -- `if(cond, a, b)`: conditional formatting -- `description.first_line()`: one-line summary -- `change_id.shortest(8)`: stable short ID -- `bookmarks`: bookmark names for a commit -- `current_working_copy`, `empty`, `conflict`: useful booleans in `jj log` - -Example: +common: `++`, `if(cond, a, b)`, `description.first_line()`, `change_id.shortest(8)`, `bookmarks`, `current_working_copy`, `empty`, `conflict`. ```bash jj --no-pager log --no-graph -n 5 -T 'change_id.shortest(8) ++ " " ++ if(description, description.first_line(), "(no description)") ++ "\n"' ``` -Start from `references/TEMPLATES.md` instead of inventing new templates unless you need something substantially different. - -## Rules +start with [`TEMPLATES.md`](TEMPLATES.md); invent only when need differs. -- Prefer `trunk()` over hardcoding `main` or `master`. -- Quote revsets and filesets in shell commands when punctuation could be interpreted by the shell. -- Prefer compact `jj --no-pager` inspection commands before widening the query. -- If a query fails to parse, check `jj --help`, `jj help -k revsets`, `jj help -k filesets`, or `jj help -k templates`. +parse fails? inspect `jj --help`, `jj help -k revsets`, `jj help -k filesets`, or `jj help -k templates`. diff --git a/modules/programs/tui/pi/skills/jujutsu/references/RECOVERY.md b/modules/programs/tui/pi/skills/jujutsu/references/RECOVERY.md index f6775a2..c3399be 100644 --- a/modules/programs/tui/pi/skills/jujutsu/references/RECOVERY.md +++ b/modules/programs/tui/pi/skills/jujutsu/references/RECOVERY.md @@ -1,118 +1,60 @@ -# Recovery and the Operation Log +# recovery and operation log -The **operation log** records every mutation to the repo — every `jj` command that changed state. Nothing is ever truly lost. This is jj's safety net: an agent that makes a mistake (bad squash, accidental abandon, wrong rebase) can always go back. +op log records every repo mutation. bad squash, abandon, rebase, restore? work recoverable. -## The three recovery primitives +## primitives -### 1. `jj undo` — reverse the last operation +first choice: ```bash jj undo ``` -The first thing to reach for. Reverses the most recent operation atomically — works for `abandon`, `squash`, `rebase`, `restore`, `describe`, and most other mutations. +reverses latest operation atomically, including abandon, squash, rebase, restore, describe. never manually unwind first. -**Prefer `jj undo` over manually reversing changes** — it's always correct and safe. - -### 2. `jj op log` — see the full operation history - -```bash -jj op log # All operations, newest first -jj op log -n 20 # Limit to 20 -jj op log -p # Include diffs of what each op changed -``` - -If you are inspecting first and do not yet need full diffs, start with the compact `jj op log` command from `references/TEMPLATES.md`. Add `-p` only after you have narrowed the relevant op IDs. - -Each operation has an `op-id`. Use these to navigate further back than a single `jj undo`. - -### 3. `jj op restore` — jump to any past state +need older operation: ```bash +jj op log +jj op log -n 20 +jj op log -p jj op restore ``` -Restores the entire repo to the state it was in at that op. **This is the nuke-from-orbit recovery** — it can undo many operations at once. Safe because the restore itself becomes a new op in the log (you can `jj undo` it if you change your mind). +start compact command from [`TEMPLATES.md`](TEMPLATES.md). narrow op IDs; only then `-p`. `op restore` restores whole repo state and itself creates recoverable op. wrong restore? `jj undo`. -## Per-change history: `jj evolog` - -The op log shows everything; `jj evolog` shows how a *single change* evolved (was rewritten, squashed into, rebased, etc.): +single change evolution: ```bash -jj evolog # Evolution of the current @ -jj evolog -r # Evolution of a specific change -jj evolog -p # Include patches between versions +jj evolog +jj evolog -r +jj evolog -p ``` -If you are inspecting first and do not yet need patches, start with the compact `jj evolog` command from `references/TEMPLATES.md`. Add `-p` only after you have narrowed the relevant version. +compact first; patch only after narrowing. useful for pre-rewrite commit version. -Useful when you want to recover an earlier *version* of a specific commit (e.g., "what did this commit look like before I squashed into it?"). +## scenarios -## Common recovery scenarios +wrong abandon just happened? `jj undo`. later? find preceding op, `jj op restore `. -### Accidentally abandoned the wrong change +squash into wrong parent or bad rebase? `jj undo`. more work followed? inspect op log and restore earlier op; understand later ops no longer active before choosing. -```bash -jj undo # If it was just now -# or -jj op log # Find the abandon op -jj op restore # Restore to before it -``` - -### A `jj squash` merged work into the wrong parent - -```bash -jj undo # Single-step undo -``` +lost work after sequence? `jj op log -p`; find last state containing work; restore it. -If you've done more work since: +need old file version: ```bash -jj op log # Locate the squash op -jj op restore # Jump back; ops after that point are dropped +jj evolog -r -p +jj restore --from ``` -### A rebase went sideways - -```bash -jj undo # Reverse the rebase entirely -``` - -### Lost work after a complex sequence - -```bash -jj op log -p # Diffs show exactly what each op did - # Find the op id where the work still existed -jj op restore -``` - -### Need a previous version of a commit's content - -```bash -jj evolog -r -p # Find the version you want -jj restore --from # Restore working-copy content from it -``` - -### Restored the wrong op-id - -```bash -jj undo # The restore is itself a recorded op -``` - -## Notes for agents - -- **Always reach for `jj undo` first** when something looks wrong. Don't try to manually unwind with new commits or `jj abandon` — `undo` is the canonical safe path. -- **The op log isn't pruned aggressively** — even a week of work is fully retrievable. -- **`jj op restore` is recorded** — it's not destructive in the way `git reset --hard` is. You can always undo a restore. -- **There is no stash/pop in jj** because every state is automatically a commit in the op log. Treat `jj undo` / `jj op restore` as the equivalent. - -## Quick reference +no stash/pop needed. each state already commit/op-log history. op log retained long enough for ordinary recovery; do not assume loss. -| Action | Command | +| need | command | |---|---| -| Undo last operation | `jj undo` | -| See all operations | `jj op log` | -| See ops with diffs | `jj op log -p` | -| Jump to past state | `jj op restore ` | -| Change evolution | `jj evolog -r ` | -| Restore file from past version | `jj restore --from ` | +| reverse latest op | `jj undo` | +| list ops | `jj op log` | +| op diffs | `jj op log -p` | +| restore repo state | `jj op restore ` | +| change history | `jj evolog -r ` | +| recover file | `jj restore --from ` | diff --git a/modules/programs/tui/pi/skills/jujutsu/references/REFINE_COMMIT.md b/modules/programs/tui/pi/skills/jujutsu/references/REFINE_COMMIT.md index 3ef1229..ff0a4fa 100644 --- a/modules/programs/tui/pi/skills/jujutsu/references/REFINE_COMMIT.md +++ b/modules/programs/tui/pi/skills/jujutsu/references/REFINE_COMMIT.md @@ -1,78 +1,42 @@ -### Squashing Changes +# refine commit -`jj squash` moves changes from one revision to another. The default is `@` → its parent; pass `--into` to target any other change. +## squash + +moves changes source -> destination. default `@` -> parent. ```bash -# Default: squash @ into its parent jj squash - -# Squash @ into a specific change (not the parent) jj squash --into -jj squash -t # short form - -# Squash a non-@ change into its parent +jj squash -t jj squash -r - -# Full explicit form: any source, any destination jj squash --from --into - -# Squash only specific paths (the rest stay in the source) jj squash path/to/file.txt jj squash --into src/auth/ ``` -**Combined description prompt**: if both source and destination have non-empty descriptions, `jj squash` opens an editor to pick a combined description — and hangs in agent environments. Always pass `-m` inline when squashing two described commits together: +both descriptions nonempty? bare command opens combine-description editor. agent must pass inline message: ```bash -jj squash --into -m "feat: Combine auth changes" +jj squash --into -m "Combine authentication changes" ``` -**Empty source**: when squashing leaves the source revision empty (no content vs. its parent), jj abandons it by default. Pass `--keep-emptied` to keep an empty placeholder instead. - -**Interactive forms to avoid**: `jj squash -i` / `jj squash --interactive` open a TUI and will hang in agent environments. Use `--from` / `--into` / paths instead. +source emptied? jj abandons by default. placeholder needed? `--keep-emptied`. -### Splitting Commits +`-i`/`--interactive`? TUI hangs. avoid. -**Warning**: `jj split` is interactive and will hang in agent environments. To divide a commit, use `jj restore` to move changes out, then create separate commits manually. +## split -### Absorbing Changes +`jj split` interactive; agent must not use. move selected changes with `jj restore`, then create separate commits manually. -Automatically distribute changes to the commits that last modified those lines: +## other tools ```bash -# Absorb working copy changes into appropriate ancestor commits -jj absorb -``` - -### Abandoning Commits - -Remove a commit entirely (descendants are rebased to its parent): - -```bash -jj abandon -``` - -### Undoing Operations - -Reverse the last jj operation: - -```bash -jj undo -``` - -This reverts the repository to its state before the previous command. Useful for recovering from mistakes like accidental `abandon`, `squash`, or `rebase`. - -### Restoring Files - -Discard changes to specific files or restore files from another revision: - -```bash -# Discard all uncommitted changes in working copy (restore from parent) -jj restore - -# Discard changes to specific files +jj absorb # distribute lines to prior owning commits +jj abandon # remove; descendants rebase to parent +jj undo # reverse last operation +jj restore # working copy from parent jj restore path/to/file.txt - -# Restore files from a specific revision jj restore --from path/to/file.txt ``` + +mutation done? `jj st`. unexpected? `jj undo` before manual repair. diff --git a/modules/programs/tui/pi/skills/jujutsu/references/REMOTES.md b/modules/programs/tui/pi/skills/jujutsu/references/REMOTES.md index 9c6c25e..fe72408 100644 --- a/modules/programs/tui/pi/skills/jujutsu/references/REMOTES.md +++ b/modules/programs/tui/pi/skills/jujutsu/references/REMOTES.md @@ -1,169 +1,78 @@ -# Named Remotes and Multi-Remote Workflows +# remotes -For pushing to a single remote (the common case), see `references/PUSH.md`. This file covers everything else: managing named remotes, selecting which remote to push to, tracking remote bookmarks, and the two canonical multi-remote setups. - -## Named remotes - -When a repo has more than one remote (e.g. `origin` = your fork, `upstream` = the canonical source), you select the target with `--remote `. +single remote push? [`PUSH.md`](PUSH.md). multiple remotes need explicit target and tracking decisions. official guide: . ```bash -jj git remote list # See all remotes and their URLs -jj git remote add upstream # Add a second remote -jj git remote rename origin fork # Rename a remote -jj git remote set-url origin # Change a remote's URL -jj git remote remove old-name # Remove a remote (and forget its bookmarks) +jj git remote list +jj git remote add upstream +jj git remote rename origin fork +jj git remote set-url origin +jj git remote remove old-name ``` -**Default remote selection**: when `--remote` is omitted, `jj git push` uses: - -1. The `git.push` config setting (if set), or -2. The remote named `origin` (if multiple remotes exist), or -3. The single remote (if only one exists) - -There is **no built-in option to push to multiple remotes in one command** — call `jj git push` once per remote. - -### Pushing the same bookmark to two remotes +no `--remote` on push? selection order: `git.push` config, then `origin` when multiple, then sole remote. one command cannot push several remotes; call once each. ```bash -jj bookmark move my-feature --to @ # Move the bookmark to current change -jj git push -b my-feature --remote fork # Push to your fork -jj git push -b my-feature --remote upstream # Push to canonical (e.g. for a PR target branch) +jj bookmark move my-feature --to @ +jj git push -b my-feature --remote fork +jj git push -b my-feature --remote upstream ``` -### Setting a default remote - -To avoid typing `--remote` repeatedly: +set default: ```bash -# Per-repo (writes to .jj/repo/config.toml) jj config set --repo git.push fork - -# Globally (writes to ~/.config/jj/config.toml) jj config set --user git.push origin ``` -### Tracking a remote bookmark - -By default, when you `jj git fetch`, remote bookmarks appear as `@` (e.g. `main@upstream`). To get a local bookmark that follows it: - -```bash -jj bookmark track main@upstream # Track upstream/main as a local 'main' -jj bookmark track 'glob:release/*@upstream' # Track all upstream release branches -``` - -Once tracked, `jj git push --tracked --remote upstream` will push all tracked bookmarks back to that remote. - -### Fetching from a specific remote +remote bookmarks appear as `@`. local should follow one? ```bash -jj git fetch --remote upstream # Fetch only from upstream -jj git fetch --all-remotes # Fetch from every configured remote +jj bookmark track main@upstream +jj bookmark track 'glob:release/*@upstream' +jj git push --tracked --remote upstream ``` -### When a push is rejected - -If the remote has moved since your last fetch, `jj git push` refuses (similar to `git push --force-with-lease`). Re-sync first: +fetch: ```bash -jj git fetch --remote # Pull the remote's current state -# (resolve any bookmark conflicts or rebase if needed) -jj git push -b --remote # Try again +jj git fetch --remote upstream +jj git fetch --all-remotes ``` -### Quick reference - -| Action | Command | -|---|---| -| List remotes | `jj git remote list` | -| Add a remote | `jj git remote add ` | -| Push to specific remote | `jj git push -b --remote ` | -| Push all tracked bookmarks to a remote | `jj git push --tracked --remote ` | -| Set default push remote (repo) | `jj config set --repo git.push ` | -| Track a remote bookmark | `jj bookmark track @` | -| Fetch one remote | `jj git fetch --remote ` | -| Fetch all remotes | `jj git fetch --all-remotes` | - -## Common multi-remote workflows +push rejected because remote moved? fetch target, resolve bookmark conflict/rebase, retry. refusal acts like lease protection. -Two canonical setups documented in [the jj docs](https://docs.jj-vcs.dev/latest/guides/multiple-remotes/). Pick the one that matches your relationship to the remotes; the config is one-time per repo. +## choose topology -**Nomenclature** (jj convention): +jj naming: `origin` writable push target; `upstream` canonical source. examples assume `main`. -- `origin` = a remote you have write access to (typically where you push) -- `upstream` = the more canonical / well-known repo (you may not have push access) -- Trunk is assumed to be `main`, so remote bookmarks are `main@origin` and `main@upstream` +### contributing fork -### Scenario 1: GitHub-style fork contributing upstream - -`upstream` is the canonical project; `origin` is your fork; you open PRs from `origin` against `upstream`. - -Typical actions: - -- Fetch from `upstream` to get the latest changes -- Push `main` to `origin` to keep your fork's `main` in sync -- Push `my-feature` to `origin`, then open a PR targeting `upstream` - -One-time setup: +features go from fork `origin` into canonical `upstream` via PR. fetch both; push fork; upstream main defines immutable trunk. ```bash -# Fetch from both remotes when you run `jj git fetch` jj config set --repo git.fetch '["upstream", "origin"]' - -# Default push target is your fork jj config set --repo git.push origin - -# Track both remote bookmarks named `main` jj bookmark track main - -# Make upstream's main the trunk (treated as immutable; rebases stop here) jj config set --repo 'revset-aliases."trunk()"' main@upstream ``` -Why these specifically: - -- Tracking `main@upstream` keeps your local `main` updated whenever you fetch from upstream -- Tracking `main@origin` means `jj git push` will also update your fork's `main` -- `trunk() = main@upstream` prevents jj from rewriting commits that are already in the canonical repo +tracking `main` tracks both matching remote bookmarks. fetch updates local main; push keeps fork main synced. trunk boundary prevents rewrite of canonical commits. -### Scenario 2: Independent repository, periodically integrating from upstream +### independent divergent repo -`origin` is a long-lived repository with its own divergent history; `upstream` is the source you occasionally pull changes from but don't contribute back to. - -Typical actions: - -- Fetch from `origin` to get the latest of your own work -- Push bookmarks to `origin`; merge PRs into `main@origin` -- Periodically fetch from `main@upstream` and merge/rebase/duplicate its changes into `main@origin` - -One-time setup: +`origin` owns long-lived line. `upstream` only occasional source. track origin main only; origin defines trunk. ```bash -# Fetch only from origin (typical case) jj config set --repo git.fetch '["origin"]' -# Or fetch from both if you want upstream changes visible on every fetch: -# jj config set --repo git.fetch '["upstream", "origin"]' - -# Default push target is origin +# optional every-fetch visibility: +# jj config set --repo git.fetch '["upstream", "origin"]' jj config set --repo git.push origin - -# Track only origin's main — do NOT track upstream's main jj bookmark track main --remote=origin jj bookmark untrack main --remote=upstream - -# Your origin defines the trunk (your main is the canonical line) jj config set --repo 'revset-aliases."trunk()"' main@origin ``` -Why these specifically: - -- Tracking only `main@origin` keeps `main@upstream` as a clearly separate reference you can `rebase`/`merge` from intentionally — it won't silently overwrite your local `main` -- `trunk() = main@origin` treats your divergent line (not upstream's) as the immutable history boundary - -### Choosing between the scenarios +upstream remains separate and integration stays explicit. -| Question | Scenario 1 | Scenario 2 | -|---|---|---| -| Do you push features back to upstream as PRs? | Yes | No | -| Should fetching from upstream update your local `main`? | Yes | No (you integrate manually) | -| Is `upstream/main` immutable from your repo's perspective? | Yes | No (you may rewrite when integrating) | -| Is `origin/main` allowed to diverge from `upstream/main`? | Minimally (just for syncing) | Yes (it's the point) | +which? contribute back and upstream fetch should move local main -> fork scenario. no contribution, origin intentionally diverges, upstream manually integrated -> independent scenario. unclear? ask before config mutation. diff --git a/modules/programs/tui/pi/skills/jujutsu/references/TEMPLATES.md b/modules/programs/tui/pi/skills/jujutsu/references/TEMPLATES.md index 435283d..b6b10ba 100644 --- a/modules/programs/tui/pi/skills/jujutsu/references/TEMPLATES.md +++ b/modules/programs/tui/pi/skills/jujutsu/references/TEMPLATES.md @@ -1,84 +1,59 @@ -# Token-Reducing Templates +# compact templates -Use inline `-T` templates for compact, agent-friendly jj output. Prefer inline `-T` use over editing repo or global jj config so the skill stays explicit and portable. +assume/tested jj 0.41.0. use commands as written. top-level `--no-pager` intentional. inline `-T` keeps repo/global config untouched. parse failure means version drift; inspect `jj --help` and `jj help -k templates`. -Assumptions: - -- Assume `jj 0.41.0` or later. -- Each template was tested with `jj 0.41.0`. -- If a template fails to parse, treat that as jj version drift and verify with `jj --help` plus `jj help -k templates`. -- Use the commands below as written. They intentionally put `--no-pager` at the top-level `jj` invocation so agent output does not depend on pager configuration. - -## `jj log` - -Tested with: `jj 0.41.0` +## log ```bash jj --no-pager log --no-graph -n 20 -T 'change_id.shortest(8) ++ if(bookmarks, " " ++ bookmarks, "") ++ if(current_working_copy, " @", "") ++ if(empty, " (empty)", "") ++ if(conflict, " (conflict)", "") ++ " " ++ if(description, description.first_line(), "(no description)") ++ "\n"' ``` -This keeps the change ID, bookmark or `@`, empty/conflict markers, and the first description line. Use `shortest(8)` instead of bare `shortest()` so IDs do not collapse to one character on `jj 0.41.0`. +keeps stable 8-char change ID, bookmarks/`@`, empty/conflict, first description. bare `shortest()` may collapse to one char. -## `jj show` - -Tested with: `jj 0.41.0` +## show ```bash jj --no-pager show --stat -T 'change_id.shortest(8) ++ if(bookmarks, " " ++ bookmarks, "") ++ if(current_working_copy, " @", "") ++ if(empty, " (empty)", "") ++ if(conflict, " (conflict)", "") ++ " " ++ if(description, description.first_line(), "(no description)") ++ "\n"' ``` -Prefer `--stat` for a compact file summary. Swap `--stat` for `--no-patch` if you want the commit summary without any file-level diff summary. - -## `jj diff` +need no file summary? replace `--stat` with `--no-patch`. -Tested with: `jj 0.41.0` +## diff ```bash jj --no-pager diff -T 'self.status_char() ++ " " ++ self.display_diff_path() ++ "\n"' ``` -Add `-r ` if you want a diff for a specific revision instead of the working copy. - -## `jj bookmark list` +specific revision? add `-r `. -Tested with: `jj 0.41.0` +## bookmark list ```bash jj --no-pager bookmark list -T 'if(self.normal_target(), self.name() ++ ": " ++ self.normal_target().change_id().shortest(8) ++ " " ++ if(self.normal_target().description(), self.normal_target().description().first_line(), "(no description)") ++ "\n", self.name() ++ ": (conflicted)\n")' ``` -Use this for ordinary bookmark inspection. If you are explicitly debugging conflicted bookmarks and need every old/new target, fall back to jj's default output. +conflicted bookmark target details needed? default output. -## `jj workspace list` - -Tested with: `jj 0.41.0` +## workspace list ```bash jj --no-pager workspace list -T 'self.name() ++ ": " ++ self.target().change_id().shortest(8) ++ " " ++ if(self.target().description(), self.target().description().first_line(), "(no description)") ++ if(self.target().empty(), " (empty)", "") ++ "\n"' ``` -This shows workspace name, working-copy change ID, description, and whether that working copy is empty. - -## `jj op log` - -Tested with: `jj 0.41.0` +## operation log ```bash jj --no-pager op log --no-graph -n 20 -T 'id.short(8) ++ " " ++ time.start().ago() ++ " " ++ description.first_line() ++ "\n"' ``` -Use this first when you need recovery context but do not yet need full diffs. Add `-p` only after you have narrowed down the interesting op IDs. +recovery context first. `-p` only after relevant IDs narrowed. -## `jj evolog` - -Tested with: `jj 0.41.0` +## evolution log ```bash jj --no-pager evolog -r --no-graph -n 20 -T 'commit.change_id().shortest(8) ++ " " ++ if(commit.description(), commit.description().first_line(), "(no description)") ++ " | " ++ operation.id().short(8) ++ " " ++ operation.description().first_line() ++ "\n"' ``` -This keeps the evolving change summary on the left and the rewriting operation on the right. - -## Not Templated +change summary left; rewriting operation right. -`jj st` and `jj status` do not expose a template flag in `jj 0.41.0`, so leave status output untemplated. The same applies to commands like `jj undo`, `jj op restore`, and `jj resolve` where the value is in the side effect, not in custom rendering. +`jj st`/`status` expose no template in 0.41.0. side-effect commands such as undo, op restore, resolve need no template. diff --git a/modules/programs/tui/pi/skills/jujutsu/references/WORKSPACES.md b/modules/programs/tui/pi/skills/jujutsu/references/WORKSPACES.md index ed9b960..be314f8 100644 --- a/modules/programs/tui/pi/skills/jujutsu/references/WORKSPACES.md +++ b/modules/programs/tui/pi/skills/jujutsu/references/WORKSPACES.md @@ -1,69 +1,43 @@ -# Parallel Workspaces +# parallel workspaces -Use `jj workspace` when multiple agents need independent working copies of the same repo. Each workspace gets its own `@` while sharing the same repo store and operation log. +assume jj 0.41.0. multiple agents need same repo? separate `@` through `jj workspace`; store and op log shared. -**Tested with jj 0.41.0** +## directory decision -This skill intentionally prefers project-local workspace directories when they are safely ignored. Directory priority for this skill: +priority is exact: 1. `.workspaces/` 2. `workspaces/` -3. Repo-local instructions such as `AGENTS.md` or `CLAUDE.md` -4. Ask the user +3. repo instructions such as `AGENTS.md` or `CLAUDE.md` +4. ask user -Do not replace this with a blanket "sibling directories only" rule. +no blanket sibling-directory rule. -## Before Creating a Workspace - -First, make sure project-local workspaces will not leak into Git history: +before create, prevent workspace metadata entering git: ```bash grep -E '^\.?workspaces/?$' .gitignore 2>/dev/null ``` -If the entry is missing, add it before `jj workspace add` and record that change using the normal workflow from `references/NEW_CHANGE.md`: - -```bash -echo ".workspaces/" >> .gitignore -``` - -Never skip this check. `jj workspace add` creates directories that contain `.jj/` metadata, and the outer Git repo must ignore them. +missing entry? add chosen directory ignore through normal describe-first workflow from [`NEW_CHANGE.md`](NEW_CHANGE.md) before workspace creation. never skip. -Use descriptive names so `jj workspace list` and `jj log` stay readable: +name descriptive: ```bash REPO_NAME=$(basename "$(jj workspace root)") WORKSPACE_PATH=".workspaces/${REPO_NAME}-" -``` - -Examples: - -- `.workspaces/myrepo-test-runner` -- `.workspaces/myrepo-reviewer-agent` -- `.workspaces/myrepo-refactor-experiment` - -Avoid generic names such as `tmp`, `wip`, or `new`. - -## Creating and Bootstrapping - -Create the workspace and move into it: - -```bash jj workspace add "$WORKSPACE_PATH" cd "$WORKSPACE_PATH" ``` -After creation: +avoid `tmp`, `wip`, `new`. workspace gets own working-copy commit and `@` marker; snapshots affect only its `@`. -- the workspace has its own working-copy commit -- it appears in log output as `@` -- it shares history and the operation log with the main workspace -- snapshots in this workspace affect only this workspace's `@` +## bootstrap -If the repo needs environment setup, bootstrap it in the new workspace before handing it to another agent: +handoff only after required environment setup: -| Marker file | Setup command | -| --- | --- | +| marker | command | +|---|---| | `package.json` | `npm install` | | `Cargo.toml` | `cargo build` | | `pyproject.toml` | `uv sync` | @@ -72,17 +46,9 @@ If the repo needs environment setup, bootstrap it in the new workspace before ha | `go.mod` | `go mod download` | | `mix.exs` | `mix deps.get` | -## Agent Handoff - -When one agent creates a workspace for another, always report: +## handoff -- the absolute workspace path -- the change ID the agent should edit -- the exact `cd` command -- the exact `jj edit ` command -- the scope boundaries - -Use a handoff like this: +always provide absolute path, stable change ID, exact `cd`, exact `jj edit `, scope boundaries, inline-message rule, status-after-mutation rule. ```text Workspace: /absolute/path/to/.workspaces/myrepo-tests @@ -97,31 +63,20 @@ Rules: - Do not modify files outside the assigned scope. ``` -Absolute paths matter. Agents lose track of relative locations more often than they lose track of change IDs. - -## Monitoring Progress +## inspect -Start from the compact `jj log` command in `references/TEMPLATES.md`, then swap in the revset you need: +use compact log from [`TEMPLATES.md`](TEMPLATES.md), changing revset: -- all workspace tips: `-r 'working_copies()'` -- one named workspace: `-r '@'` +- all tips: `-r 'working_copies()'` +- one: `-r '@'` -Examples of the revsets themselves: +syntax: [`QUERY_LANGUAGES.md`](QUERY_LANGUAGES.md). -```bash -working_copies() -reviewer@ -``` - -See `references/QUERY_LANGUAGES.md` for the revset syntax behind those examples. - -## Combining Results +## integrate -When a workspace finishes its work, bring that change back to the main line and retire the workspace. Do not decide silently; ask the user which strategy they want. +result ready? do not silently pick strategy. ask user: rebase into default workspace, explicit merge, or bookmark/PR. -### Strategy 1: Rebase into the Default Workspace - -Use this when one developer is orchestrating multiple agents and the result should land as ordinary commits in the default workspace. +rebase ordinary commits: ```bash jj rebase -s -d @ @@ -129,37 +84,22 @@ jj workspace forget rm -rf "$WORKSPACE_PATH" ``` -If the repo uses bookmarks for shipping work, move or create the bookmark after the rebase using the normal push workflow from `references/PUSH.md`. - -### Strategy 2: Keep an Explicit Merge - -Use this when both lines of work are independently meaningful and the merge structure should remain visible: +visible merge when lines independently meaningful: ```bash -jj new -m "merge: combine parallel work" +jj new -m "Combine parallel work" ``` -### Strategy 3: Push a Bookmark and Open a PR - -Use this when the work needs human review before landing: +human review: ```bash jj bookmark create my-feature -r jj git push -b my-feature ``` -Decision guide: +solo parallel work usually rebase. review required means PR. meaningful dual lines means merge. bookmark shipping after rebase follows [`PUSH.md`](PUSH.md). -| Situation | Default suggestion | -| --- | --- | -| Solo developer running multiple local agents | Strategy 1 | -| Long-lived feature with checkpoints | Strategy 1, then push a bookmark when ready | -| Human review required | Strategy 3 | -| Both lines of work are independently meaningful | Strategy 2 | - -If the context is ambiguous, suggest Strategy 1 first and ask whether the user wants the result to land in the default workspace or as a PR. - -## Listing and Cleaning Up +## cleanup and stale state ```bash jj workspace list @@ -167,43 +107,22 @@ jj workspace forget rm -rf "$WORKSPACE_PATH" ``` -If you need to inspect `jj workspace list` output as an agent, use the compact command from `references/TEMPLATES.md`. - -`jj workspace forget` only unregisters the workspace. It does not delete files from disk. - -## `update-stale` +forget first; it does not delete files. -If another workspace rewrites the commit your workspace had checked out, jj marks that workspace as stale. Use this first: +base rewritten elsewhere and workspace stale? ```bash jj workspace update-stale jj st ``` -Do not improvise a manual repair before trying `update-stale`. If the old operation is gone, jj can create a recovery commit with the current working-copy contents instead of silently discarding them. - -## Conflict Avoidance - -| Risk | Recommended mitigation | -| --- | --- | -| Build outputs or generated files | Ignore them or give each workspace separate output paths | -| Shared config files | Assign a single owner for that file or change it serially | -| Lockfiles / dependency updates | Let one task own dependency changes | -| Same source files across workspaces | Redesign the task boundary or serialize the work | - -## Critical Rules - -1. Never skip the `.gitignore` check for project-local workspace directories. -2. Always follow the directory priority: `.workspaces/` -> `workspaces/` -> repo instructions -> ask. -3. Use descriptive names: `${REPO_NAME}-`, not `tmp`. -4. Bootstrap the workspace before handing it to another agent. -5. Report the absolute path, change ID, and next commands when a workspace is ready. -6. Run `jj workspace forget` before deleting the directory. -7. Ask before choosing between rebase, merge, or PR integration. -8. Use `jj workspace update-stale` as the first response to a stale workspace. +use before manual repair. old operation unavailable? jj may create recovery commit from current files rather than discard. -## Reference +## avoid collisions -Convention adapted from [edmundmiller/dotfiles `using-jj-workspaces`](https://lobehub.com/skills/edmundmiller-dotfiles-using-jj-workspaces). +- generated/build outputs: ignore or separate paths. +- shared config: one owner or serialize. +- lockfile/dependencies: one task owns. +- same source files: redesign boundary or serialize. -Additional handoff, monitoring, stale-workspace, and conflict-avoidance patterns were adapted from [joshuadavidthomas/agent-skills `jj`](https://github.com/joshuadavidthomas/agent-skills/tree/main/jj) and its [`workspaces.md`](https://raw.githubusercontent.com/joshuadavidthomas/agent-skills/main/jj/workspaces.md), while intentionally preserving this skill's local `.workspaces/` / `workspaces/` directory priority and local change-creation workflow. +absolute handoff, ignore check, descriptive name, bootstrap, integration question, forget-before-delete, and update-stale-first are mandatory. diff --git a/modules/programs/tui/pi/skills/nix-debug/SKILL.md b/modules/programs/tui/pi/skills/nix-debug/SKILL.md index e894a69..5e99970 100644 --- a/modules/programs/tui/pi/skills/nix-debug/SKILL.md +++ b/modules/programs/tui/pi/skills/nix-debug/SKILL.md @@ -1,21 +1,17 @@ --- name: nix-debug -description: Use this skill to debug Nix expressions, flake outputs, modules, and option values with `nix repl`. Prefer it when investigating evaluation errors, missing attributes, unexpected option values, derivation inputs, or output structure. Use `nix repl` instead of `nix eval` for inspection because the interactive REPL is faster for repeated queries. +description: Debug Nix expressions, flakes, modules, options, derivations, and outputs through an interactive nix repl session. --- -## Nix Debug +# nix debug -Prefer one `nix repl` session over many `nix eval` calls. +need repeated inspection? one `nix repl`; not many `nix eval` calls. -Workflow: - -1. Start from the narrowest useful target. -2. Load the flake/expression: `nix repl`, then `:lf .`, or `nix repl ./path/to/file.nix`. -3. Inspect parent attrsets with `builtins.attrNames` before deep paths. -4. Evaluate small subexpressions until the failing edge is clear. -5. Report the exact attr path, value, or error. - -Useful probes: +1. choose narrowest useful target. +2. load: `nix repl` then `:lf .`, or `nix repl ./path/to/file.nix`. +3. key unknown? inspect parent with `builtins.attrNames`. never guess host, user, output. +4. walk missing path one segment at time. evaluate small expressions until failing edge known. +5. report exact attr path, value, or error. ```nix builtins.attrNames inputs @@ -29,10 +25,6 @@ builtins.attrNames overlays :p packages.${builtins.currentSystem}.foo.drvAttrs ``` -Rules: +inspect realized `config` first. need type/declaration metadata? then inspect `options`. special attr name? quote: `foo."bar-baz"`. -- Do not default to `nix eval` for interactive debugging. -- Do not guess host/user/output keys when `builtins.attrNames` can confirm them. -- Walk missing attrs one segment at a time. -- Inspect realized `config` first; inspect `options` only for type/declaration metadata. -- Use quoted attrs for special names: `foo."bar-baz"`. +interactive debug means `nix repl` default. `nix eval` only when interaction not needed. diff --git a/modules/programs/tui/pi/skills/nix-index/SKILL.md b/modules/programs/tui/pi/skills/nix-index/SKILL.md index ad9093f..d7d8382 100644 --- a/modules/programs/tui/pi/skills/nix-index/SKILL.md +++ b/modules/programs/tui/pi/skills/nix-index/SKILL.md @@ -1,13 +1,11 @@ --- name: nix-index -description: Use this skill to locate which Nix package provides a command or file with `nix-locate` and the existing local database. Do not use it to build, refresh, inspect, or manage the `nix-index` database. +description: Locate Nix packages providing commands or files with nix-locate and the existing local database; never manage that database. --- -# Nix Index +# nix index -Use `nix-locate` to map files/commands to packages. Do not run or manage `nix-index`. - -Common queries: +need package owning command/file? use `nix-locate`. never run or manage `nix-index`; never suggest database build, refresh, deletion, or cache maintenance. ```bash nix-locate --top-level --whole-name --type x --type s '/bin/rg' @@ -18,19 +16,13 @@ nix-locate --top-level 'python.*/site-packages/pandas' nix-locate --whole-name '/bin/hello' ``` -Command-not-found workflow: +command missing: -1. Try `nix-locate --top-level --whole-name --type x --type s "/bin/foo"`. -2. If empty, broaden to `nix-locate --top-level --type x 'bin/foo'` or regex. -3. If the file may live in a split output, retry without `--top-level`. -4. If still empty, fall back to `nix-search-tv`. +1. exact executable: `nix-locate --top-level --whole-name --type x --type s "/bin/foo"`. +2. empty? broaden: `nix-locate --top-level --type x 'bin/foo'` or regex. +3. split output possible? retry without `--top-level`. +4. still empty? fall back to `nix-search-tv`. -Result handling: +need installable attrs? `--top-level`. known path? `--whole-name`. executable? `--type x --type s`. too broad? narrow path and type. -- Use `--top-level` for installable package attrs. -- Use `--whole-name` for known full paths. -- Add `--type x --type s` for executables. -- Multiple matches are normal; report the likely package first plus close alternatives. -- For too many results, add `--whole-name`, restrict the path such as `/bin/foo`, or add `--type` filters. -- For metadata, run `nix-search-tv preview --indexes nixpkgs `. -- Never suggest database build/refresh/delete/cache maintenance. +multiple matches normal. likely package first; close alternatives after. metadata needed? `nix-search-tv preview --indexes nixpkgs `. diff --git a/modules/programs/tui/pi/skills/nix-search/SKILL.md b/modules/programs/tui/pi/skills/nix-search/SKILL.md index ab5f6a6..1cfec23 100644 --- a/modules/programs/tui/pi/skills/nix-search/SKILL.md +++ b/modules/programs/tui/pi/skills/nix-search/SKILL.md @@ -1,15 +1,17 @@ --- name: nix-search -description: Use this skill to search NixOS packages and options with `nix-search-tv`. Query package details, source locations, and configured NixOS, Home Manager, and flake option indexes. +description: Search packages and configured NixOS, Home Manager, flake, and custom options with nix-search-tv. --- -# Nix Search +# nix search -Use `nix-search-tv` for packages/options. Builtin indexes: `home-manager`, `nixos`, `nixpkgs`, `noogle`, `nur`. Custom option indexes: `authentik-nix`, `determinate`, `disko`, `home-manager-nixos`, `hylix`, `lanzaboote`, `nix-flatpak`, `nix-index-database`, `nixcord`, `noctalia`, `nvf`, `overzicht`, `sops-nix`, `sops-nix-home-manager`, `spicetify-nix`, `stylix`, `stylix-home-manager`, `zen-browser`. +package or option unknown? use `nix-search-tv`. -This repo wires builtin indexes through `settings.indexes` and custom option sources through `settings.experimental.options_file`; both use `--indexes `. +builtin indexes: `home-manager`, `nixos`, `nixpkgs`, `noogle`, `nur`. -Commands: +custom options: `authentik-nix`, `determinate`, `disko`, `home-manager-nixos`, `hylix`, `lanzaboote`, `nix-flatpak`, `nix-index-database`, `nixcord`, `noctalia`, `nvf`, `overzicht`, `sops-nix`, `sops-nix-home-manager`, `spicetify-nix`, `stylix`, `stylix-home-manager`, `zen-browser`. + +repo wiring: builtin via `settings.indexes`; custom via `settings.experimental.options_file`. both queried with `--indexes `. ```bash nix-search-tv print --indexes nixpkgs @@ -24,17 +26,9 @@ nix-search-tv source --indexes noctalia programs.noctalia.settings.bar nix-search-tv homepage --indexes nixpkgs firefox ``` -Notes: - -- First run indexes data; later runs use cache. -- `print` prefixes source names, e.g. `stylix/ stylix.image`. -- Use explicit `--indexes` to avoid ambiguity across custom sources. -- Use `NO_COLOR=1` for parseable output. -- Use `--json` with `preview` for automation; selected key appears in `_key`. -- If `cache.txt` is missing, run `print --indexes ` once. -- If stale, remove `~/.cache/nix-search-tv/` and rerun. +first run builds index data; later uses cache. `cache.txt` missing? run `print --indexes ` once. stale? remove `~/.cache/nix-search-tv/` then rerun. -Patterns: +ambiguity possible? explicit `--indexes`. parse output? `NO_COLOR=1`; automation? `preview --json`, selected key in `_key`. `print` prefixes source, e.g. `stylix/ stylix.image`. ```bash nix-search-tv print --indexes nixpkgs | rg -i firefox diff --git a/modules/programs/tui/pi/skills/nvf-config/SKILL.md b/modules/programs/tui/pi/skills/nvf-config/SKILL.md index 473bc62..098b489 100644 --- a/modules/programs/tui/pi/skills/nvf-config/SKILL.md +++ b/modules/programs/tui/pi/skills/nvf-config/SKILL.md @@ -1,64 +1,49 @@ --- name: nvf-config -description: Generate, edit, or review Neovim configuration in NVF and Nix form using verified docs instead of guessed APIs. Use for `programs.nvf.settings.*`, `setupOpts`, `keymaps`, language modules, plugin options, `mkLuaInline`, `luaConfigPre` snippets, and translating upstream plugin docs into NVF modules. +description: Generate, edit, or review Neovim configuration in NVF and Nix from verified option and plugin documentation. --- -# NVF Config +# nvf config -Work NVF-first. Treat Neovim config as Nix/NVF, not plain Lua. +NVF-first. config is Nix/NVF, not generic Lua. option or API unknown? inspect. never guess. -Core rule: do not guess NVF options, Neovim APIs, or plugin setup keys. Prefer a small verified Nix snippet over plausible Lua. +## lookup order -Lookup order before editing: +1. existing repo config. +2. local NVF option docs/search. +3. NVF manual/options. +4. exact NVF module source. +5. installed Neovim help for built-ins. +6. exact plugin docs/source. +7. Context7 when available. +8. web/GitHub fallback. +9. inference only when marked uncertain. -1. Existing repo config. -2. Local NVF option docs/search tools. -3. NVF manual/options reference. -4. NVF module source for the exact option path. -5. Installed Neovim help for built-ins. -6. Plugin docs/source for plugin APIs. -7. Context7, if available. -8. Web or GitHub fallback. -9. Inference only if clearly marked uncertain. +memory conflicts with local docs? local wins. -Do not skip directly to writing code from memory. - -Repo patterns to preserve: +## preserve repo shape - `programs.nvf.settings.vim = { ... };` - modules under `modules/home/tui/neovim/` - `keymaps = [ { key = ...; mode = ...; action = ...; } ];` - plugin tables in `setupOpts` -- `lib.generators.mkLuaInline` for Lua functions inside Nix attrs -- `neovim.luaConfigPreSnippets` for early startup logic, autocmds, globals, or larger raw Lua -- nearby helper imports, grouping, list-vs-attrset style, and `keep-sorted` comments -- before adding config, inspect nearby autocmd conventions, language module layout, custom Nix helpers, and existing helper functions -- comments short, local, and only for non-obvious intent - -NVF rules: - -- Prefer exact `programs.nvf.settings.*` options over raw Lua. -- Confirm option path, type, shape, and whether an NVF wrapper exists. -- Read module source when docs are unclear. -- Keep plugin configuration in `setupOpts` when the NVF module exposes a plugin block. -- Keep Lua valid inside Nix strings and escape `${...}` correctly. -- Use raw Lua only when NVF lacks the feature, cannot express needed callbacks/functions, or the repo already handles that category through `luaConfigPreSnippets`. -- Static keymaps should use NVF keymaps, not `vim.keymap.set()`. -- Do not assume lazy.nvim examples map directly onto NVF options. -- For built-ins, useful help pages include `:help lua`, `api`, `deprecated`, `autocmd-events`, `vim.keymap.set()`, `vim.diagnostic`, `lsp`, and `treesitter`. -- If local docs disagree with memory or upstream examples, local docs win. -- Preserve attribute naming style; prefer explicit nested attrs when matching nearby code; use `let` only when it simplifies the module. - -Plugin/API rules: - -- Identify the exact plugin repo and version when relevant. -- Check NVF exposure before upstream Lua examples. -- Prefer plugin `doc/*.txt`, README setup docs, examples, `setup()` defaults, then source. -- Use plugin issues/discussions only when official docs and source are missing. -- Do not use fields missing from docs/defaults/source. -- Translate confirmed Lua config into NVF/Nix instead of copying wholesale Lua. - -Common shapes: +- `lib.generators.mkLuaInline` for Lua functions in Nix attrs +- `neovim.luaConfigPreSnippets` for early logic, autocmds, globals, larger raw Lua +- nearby imports, helpers, grouping, list/attrset style, `keep-sorted` controls +- nearby autocmd conventions, language layout, helper functions: inspect before adding +- comments short, local, non-obvious intent only + +## decisions + +exact NVF option exists? use it. confirm path, type, shape, wrapper. docs unclear? read module source. + +plugin block exposes `setupOpts`? configure there. static mapping? NVF keymaps, not `vim.keymap.set()`. lazy.nvim example? no direct mapping assumption. attribute shape? match nearby style; prefer explicit nested attrs when nearby. `let` only when module gets simpler. + +raw Lua allowed only when NVF cannot express feature/callback, or repo already owns category through `luaConfigPreSnippets`. Lua inside Nix must remain valid; escape `${...}`. + +plugin API? identify repo and relevant version. inspect in order: NVF exposure, `doc/*.txt`, README setup, examples, `setup()` defaults, source. issues/discussions last. field absent from docs/defaults/source? do not use. translate verified Lua into Nix; do not copy wholesale. + +built-in docs useful: `:help lua`, `api`, `deprecated`, `autocmd-events`, `vim.keymap.set()`, `vim.diagnostic`, `lsp`, `treesitter`. ```nix _: { @@ -106,9 +91,9 @@ _: { } ``` -Stop and state uncertainty if the NVF path, option shape, plugin API/version, installed plugin, required unrelated restructure, old-dotfile-only field, or docs/source absence is unclear. +unclear path, shape, API/version, installed plugin, unrelated restructure, old-dotfile field, or missing evidence? stop; state uncertainty. -When returning a snippet, include assumptions, target file, code, sources checked, validation command, and uncertainties. Use repo targets when known: +return snippet with assumptions, target file, code, sources checked, validation command, uncertainties. known repo target? use exact name: ```sh nix flake check @@ -116,4 +101,4 @@ home-manager build --flake .# nixos-rebuild build --flake .# ``` -Use the repo's actual target names when known. Accuracy is more important than completeness. +accuracy beats completeness. diff --git a/modules/programs/tui/pi/skills/simplify/SKILL.md b/modules/programs/tui/pi/skills/simplify/SKILL.md index cca095c..f04b0b8 100644 --- a/modules/programs/tui/pi/skills/simplify/SKILL.md +++ b/modules/programs/tui/pi/skills/simplify/SKILL.md @@ -1,63 +1,69 @@ --- name: simplify -description: "Simplify settled, recently changed code for clarity, reuse, quality, and efficiency while preserving behavior. Use after implementation and before review; use ce-debug for bugs." +description: "Run only when user explicitly invokes `/simplify` or explicitly asks to use the simplify skill; simplify settled changed code while preserving behavior. Ordinary implementation, review, cleanup, refactoring, or code changes must never trigger it." argument-hint: "[blank to simplify current branch changes, or describe what to simplify]" --- -Simplify recently changed code for clarity, reuse, quality, and efficiency while preserving exact behavior. Prioritize readable, explicit code over compact code — fewer lines is not the goal. +# simplify -## Step 1: Identify scope +activation gate: user invoked `/simplify` or explicitly asked for simplify skill? continue. anything else—including ordinary code change, implementation, review, cleanup, refactor—do not run. -Resolve the simplification scope in this order: +bug diagnosis? use `ce-debug`; simplify is not debugger. -1. **User-named scope** is authoritative; do not widen it. -2. **Otherwise, in git**, use the current branch versus its base. Without a usable base, use staged and unstaged changes (`git diff HEAD`). -3. **Outside git or without a diff**, use files the user named or that were edited earlier in the conversation. +goal: clarity, reuse, quality, efficiency. exact behavior stays. readable explicit code beats fewer lines. -If none of the above produces a non-empty scope, stop and ask the user what to simplify rather than guessing. Use the platform's blocking question tool: `AskUserQuestion` in Claude Code (call `ToolSearch` with `select:AskUserQuestion` first if its schema isn't loaded), `request_user_input` in Codex, `ask_question` in Antigravity CLI (`agy`), `ask_user` in Pi (requires the `pi-ask-user` extension). Fall back to numbered options in chat only when no blocking tool exists in the harness or the call errors (e.g., Codex edit modes) — not because a schema load is required. Never silently skip the question. +## 1. scope -**Preflight.** If the scope has no substantive human-authored code — only documentation, generated or vendored files, dependencies or lockfiles, or mechanical churn — report that there is nothing to simplify and stop without reviewers. For mixed scopes, retain only the code. This is a kind gate, never a size gate: explicit small scopes still run, and callers own any size or cost threshold. +resolve in order: -When the platform's task-tracking capability is available, show the review, apply, and verification outcomes without creating one task per reviewer. Otherwise continue without simulating a task list in chat. +1. user names scope? authoritative. never widen. +2. otherwise in git: current branch versus base. no usable base? staged + unstaged via `git diff HEAD`. +3. outside git/no diff: user-named files or files edited earlier in conversation. -## Step 2: Launch 3 review agents in parallel +empty scope? ask what to simplify. use blocking question tool: `AskUserQuestion` in Claude Code (`ToolSearch` with `select:AskUserQuestion` first if schema absent), `request_user_input` in Codex, `ask_question` in Antigravity CLI (`agy`), `ask_user` in Pi with `pi-ask-user`. no blocking tool or call errors? numbered chat options. schema load alone not failure. never silently skip question. -Dispatch three generic subagents — code-reuse, code-quality, and efficiency reviewers — via the platform's subagent primitive (`Agent`/`Task` in Claude Code, `spawn_agent` in Codex) where available; otherwise run the reviews inline or serially. For each reviewer, read its prompt asset from this skill's directory and pass the **full file content** as the subagent's prompt, together with the resolved scope (the full diff or file set) so it has complete context: +preflight: substantive human-authored code absent—only docs, generated/vendor, dependencies/lockfiles, mechanical churn? report nothing to simplify; stop before reviewers. mixed? retain code only. kind gate, never size gate. explicit tiny scope still runs; caller owns cost threshold. + +task tracking available? show review, apply, verification outcomes. no one-task-per-reviewer. unavailable? continue; no fake chat task list. + +## 2. three reviews + +read these assets fully, then pass full verbatim content plus full resolved diff/file set: - `personas/code-reuse-reviewer.md` - `personas/code-quality-reviewer.md` - `personas/efficiency-reviewer.md` -Do not paraphrase these rubrics from memory — read each file and pass it verbatim, or the reviewer loses the gating rules that keep the pass behavior-preserving. +dispatch generic subagents through harness primitive (`Agent`/`Task` in Claude Code, `spawn_agent` in Codex). no primitive? inline/serial. -**Bounded dispatch.** Queue the three reviewers and launch only as many as the harness accepts at once; treat a concurrency/active-agent-limit error as backpressure (leave the reviewer queued and retry after a slot frees), not as reviewer failure. If a dispatch fails for any other reason, run that reviewer's pass inline in the parent context using the same prompt asset, and disclose the substitution in one line. +queue all three. launch only accepted concurrency. active-agent/concurrency limit means backpressure: keep queued, retry after slot frees. other dispatch failure? run same asset inline; disclose substitution in one line. -**Model selection.** Use the platform's balanced mid-tier model for these reviewers when the current harness exposes a known override. In Claude Code this is the Sonnet class. In Codex, apply this tier only when the active dispatch primitive exposes an explicit model or custom-agent selector; task wording alone does not select a different model. Otherwise omit the override and inherit the parent model -- a working pass on the parent model beats a broken dispatch. +model override exposed and known? balanced mid-tier. Claude Code: Sonnet. Codex: only explicit model/custom-agent selector counts; wording cannot select model. otherwise inherit parent. working parent pass beats broken dispatch. -**Permission mode.** Omit the `mode` parameter on the dispatch call so the user's configured permission settings apply. +omit dispatch `mode`; user permission config wins. -## Step 3: Fix issues +## 3. decide and edit -Proceed only after all three review outcomes are complete, whether returned by subagents or produced inline. Apply worthwhile findings directly; record false positives and low-value findings as skipped without asking the user. +wait for all three outcomes. worthwhile and proven? apply. false positive/low value? skip without asking; record. -Inspect beyond the resolved scope when needed to evaluate a finding, but edit only that scope and its necessary import/export seams. For a user-named file or directory scope, those seams must also be inside it; skip any fix that would edit outside the mutation boundary. +inspect outside scope if needed to judge. edits limited to scope plus necessary import/export seams. user named file/directory? seams also must stay inside it. required edit crosses mutation boundary? skip. -Each fix must preserve outputs, errors, side effects, and ordering. If that cannot be established, skip it. +preserve outputs, errors, side effects, ordering. cannot prove? skip. -An interface or data shape that existed only in an earlier iteration of the current unshipped scope is not protected behavior once you verify it has no deployed, persisted, public, external, dependent-branch, or in-repo caller outside the resolved scope. Remove that compatibility path only when every required caller update fits the existing mutation boundary; otherwise preserve it. +compat path exists only from earlier unshipped iteration? removable only after proving no deployed, persisted, public, external, dependent-branch, or in-repo caller outside scope. every caller update must fit mutation boundary; otherwise preserve. -**Never simplify away a safety check.** Preserve trust-boundary validation, data-loss protection, security checks, and accessibility affordances. Skip any finding that would thin or remove one. +safety check? never thin/remove. preserve trust-boundary validation, data-loss protection, security checks, accessibility affordances. -**Honor caller-passed structure pins.** A plan path passed with the structure-pin constraint is context, not scope. Preserve its `session-settled:` Key Technical Decisions, including deliberate duplication or separation. +caller supplied plan path with structure-pin? context, not scope. preserve `session-settled:` Key Technical Decisions, including deliberate duplication/separation. -## Step 4: Verify behavior is preserved +## 4. verify -Run project-wide typecheck and lint. Run tests matched to blast radius: scoped tests for local changes, broader tests for shared or wide-reach changes, and the full suite when the runner cannot scope tests. +run project-wide typecheck and lint. tests match blast radius: scoped for local, broader for shared/wide, full suite when runner cannot scope. -Report failures with the check name and relevant output. Fix simplification-caused failures or revert the responsible change; never relax assertions, weaken types, or skip tests. +failure? report check and relevant output. caused by simplification? fix or revert responsible change. never weaken assertion/type or skip test. -If no test suite, lint, or typecheck is configured, state that explicitly in the summary; do not silently skip verification. +no configured test, lint, or typecheck? state explicitly. -## Step 5: Summarize +## 5. report -Summarize what was already sound and what improved. Report applied counts by reuse, quality, and efficiency; skipped count; and check outcomes. If nothing changed, say so. Do not use net lines removed as the success metric. +say what was already sound and what improved. counts: reuse applied, quality applied, efficiency applied, skipped. include check outcomes. no changes? say so. net lines removed is not success metric. diff --git a/modules/programs/tui/pi/skills/simplify/personas/code-quality-reviewer.md b/modules/programs/tui/pi/skills/simplify/personas/code-quality-reviewer.md index e087986..76453c0 100644 --- a/modules/programs/tui/pi/skills/simplify/personas/code-quality-reviewer.md +++ b/modules/programs/tui/pi/skills/simplify/personas/code-quality-reviewer.md @@ -1,17 +1,21 @@ -You are the **Code Quality Reviewer**. You receive recently changed code as a diff or resolved file set. Find hacky patterns, while preserving exact behavior. Review for: +# code quality reviewer -1. **Redundant state**: state that duplicates existing state, cached values that could be derived, observers/effects that could be direct calls -2. **Parameter sprawl**: adding new parameters to a function instead of generalizing or restructuring existing ones -3. **Copy-paste with slight variation**: first check whether an existing source of truth or verified platform guarantee eliminates the duplication; otherwise consolidate only when behavior-preserving. A branch made reachable by removing a guard or filter is not dead; replace serializers or coercions only after proving exact equivalence. -4. **Leaky abstractions**: exposing internal details that should be encapsulated, or breaking existing abstraction boundaries -5. **Stringly-typed code**: using raw strings where constants, enums (string unions), or branded types already exist in the codebase -6. **Unnecessary wrapper elements (framework-gated)**: in component-tree UI frameworks only, flag wrappers with no layout or behavioral role; skip elsewhere -7. **Nested conditionals**: ternary, if/else, or switch nesting 3+ levels deep -8. **Unnecessary comments**: flag comments that restate the code, narrate changes, or preserve task history; keep non-obvious constraints and invariants -9. **Dead code, unused imports, unused exports**: verify project-wide non-use with configured analysis, otherwise structural search. Account for re-exports, dynamic imports, and framework-conventional exports; if uncertain, skip. -10. **Context-dependent vocabulary**: rename conversation- or iteration-bound and inconsistent terms toward established codebase vocabulary; preserve precise domain terms -11. **Pre-release compatibility scaffolding**: remove forms superseded entirely within the current branch only after verifying they were never deployed, persisted, public, external, or consumed by a dependent branch; if uncertain, skip +receive resolved diff/files. find hacky patterns. exact behavior must stay. -**Balance.** Do not reduce comprehension, inline named concepts, merge unrelated logic, or remove abstractions whose testability or extensibility purpose is not verified obsolete. +check: -Return each finding as: location (`file:line`), the issue, and the concrete fix. If there is nothing to flag, say so explicitly. +1. redundant state, derivable cache, observer/effect replaceable by direct call. +2. parameter sprawl where existing structure should generalize. +3. near-copy. first seek source of truth or verified platform guarantee. otherwise consolidate only with equivalence proof. removed guard/filter makes branch reachable, not dead. serializer/coercion replacement needs exact proof. +4. abstraction leak or broken boundary. +5. raw strings where established constant, union, enum, branded type exists. +6. component-tree UI only: wrapper without layout/behavior. elsewhere skip. +7. conditional nesting 3+ levels. +8. comments restating code, narrating change/history. keep non-obvious constraints/invariants. +9. dead code/import/export. verify project-wide with configured analysis, else structural search. account for re-export, dynamic import, framework exports. uncertain? skip. +10. conversation/iteration vocabulary inconsistent with codebase. rename toward established terms; preserve precise domain terms. +11. pre-release compatibility superseded within current branch. remove only after proving never deployed, persisted, public, external, or used by dependent branch. uncertain? keep. + +balance: comprehension wins. do not inline named concepts or merge unrelated logic. abstraction supports testability/extensibility? preserve unless purpose proven obsolete. + +return each: `file:line`, issue, concrete fix. none? say explicitly. diff --git a/modules/programs/tui/pi/skills/simplify/personas/code-reuse-reviewer.md b/modules/programs/tui/pi/skills/simplify/personas/code-reuse-reviewer.md index 1189e4e..f6ffdb1 100644 --- a/modules/programs/tui/pi/skills/simplify/personas/code-reuse-reviewer.md +++ b/modules/programs/tui/pi/skills/simplify/personas/code-reuse-reviewer.md @@ -1,7 +1,11 @@ -You are the **Code Reuse Reviewer**. You receive recently changed code as a diff or resolved file set. Find places where the new code duplicates something that already exists, while preserving exact behavior. For each change: +# code reuse reviewer -1. **Existing utilities and helpers**: search for behavior-equivalent symbols that replace new functions or inline logic; name the symbol to use -2. **Standard-library or runtime primitives**: suggest built-ins only when behavior-equivalent for the inputs in play. Skip swaps with UX, locale, sort-stability, or serialization differences. -3. **Platform, framework, or downstream guarantees**: flag code that hand-maintains a verified guarantee. Name the provider and resulting simplification. Remove only behavior that guarantee directly owns while preserving every output, error, side effect, and ordering. Keep value transformations before downstream projection. Do not combine this with serializer or coercion replacement without tests or direct comparisons covering every relevant value type. Newly reachable branches are not dead code. +receive resolved diff/files. find new duplication. exact behavior must stay. -Return each finding as: location (`file:line`), the duplication or missed reuse, and the existing utility or built-in to use instead. If there is nothing to flag, say so explicitly. +check: + +1. existing equivalent helper/utility. search; name symbol. +2. standard/runtime primitive. only if equivalent for actual inputs. UX, locale, stable sort, serialization differs? skip. +3. platform/framework/downstream guarantee. verify provider, then remove only work provider owns. preserve outputs, errors, effects, ordering, and transformations before projection. serializer/coercion swap needs tests or direct comparisons for every relevant type. removed guard makes branch reachable? branch not dead. + +return each: `file:line`, duplication, exact existing replacement. none? say explicitly. diff --git a/modules/programs/tui/pi/skills/simplify/personas/efficiency-reviewer.md b/modules/programs/tui/pi/skills/simplify/personas/efficiency-reviewer.md index 7198c10..410c922 100644 --- a/modules/programs/tui/pi/skills/simplify/personas/efficiency-reviewer.md +++ b/modules/programs/tui/pi/skills/simplify/personas/efficiency-reviewer.md @@ -1,11 +1,15 @@ -You are the **Efficiency Reviewer**. You receive recently changed code as a diff or resolved file set. Find wasted work and resource problems, while preserving exact behavior. Review for: +# efficiency reviewer -1. **Unnecessary work**: redundant computations, repeated file reads, duplicate network/API calls, N+1 patterns -2. **Missed concurrency**: independent operations run sequentially when they could run in parallel -3. **Hot-path bloat**: new blocking work added to startup or per-request/per-render hot paths -4. **Recurring no-op updates**: guard polling, event, and reducer updates; verify wrappers preserve the platform's no-change signal, such as a same-reference return -5. **Unnecessary existence checks**: pre-checking file/resource existence before operating (TOCTOU anti-pattern) — operate directly and handle the error -6. **Memory**: unbounded data structures, missing cleanup, event listener leaks -7. **Overly broad operations**: reading entire files when only a portion is needed, loading all items when filtering for one +receive resolved diff/files. find waste; preserve exact behavior. -Return each finding as: location (`file:line`), the inefficiency, and the concrete fix. If there is nothing to flag, say so explicitly. +check: + +- repeated computation/read/network call; N+1. +- independent sequential operations that can run concurrently. +- blocking work added to startup, request, render hot path. +- recurring no-op polling/event/reducer updates. wrapper must preserve platform no-change signal, e.g. same-reference return. +- existence precheck before operation: TOCTOU. operate, handle error. +- unbounded structures, missing cleanup, listener leaks. +- whole file/all items loaded when narrow read/filter works. + +return each: `file:line`, inefficiency, concrete fix. none? say explicitly. -- 2.51.2