@justinforfun/redo-skill 0.1.1 → 0.1.3

package/README.md

@@ -16,6 +16,8 @@ The installer supports:
 - Codex CLI
 - Claude Code
 
+The installer detects supported tools on the local machine. Detected tools are selected by default; tools that are not detected are left unselected but can still be chosen. If you choose an undetected tool, the installer asks for confirmation before writing to its default directory.
+
 ## Invocation
 
 ```text
@@ -44,6 +46,8 @@ For each technology, `redo` reconstructs:
 - Candidate options and their costs
 - Why the chosen design won
 - Key trade-offs
+- Transferable design patterns in sibling systems
+- Boundary cases and counterexamples
 - Technical debt introduced
 - Debt that was later resolved
 - Pain points that still remain

package/bin/install.js

@@ -4,6 +4,7 @@ import fs from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
 import process from 'node:process';
+import { execFile } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 
 import chalk from 'chalk';
@@ -28,7 +29,15 @@ const targets = [
         destination: path.join(os.homedir(), '.agents', 'skills', 'redo')
       }
     ],
-    trigger: '$redo kafka, redo kafka, or select redo from the skill picker'
+    trigger: '$redo kafka, redo kafka, or select redo from the skill picker',
+    detectors: [
+      {
+        type: 'path',
+        value: path.join(os.homedir(), '.agents'),
+        label: '~/.agents'
+      }
+    ],
+    missingReason: 'Codex local skill directory was not detected.'
   },
   {
     id: 'codex-cli',
@@ -41,7 +50,20 @@ const targets = [
         destination: path.join(process.env.CODEX_HOME || path.join(os.homedir(), '.codex'), 'skills', 'redo')
       }
     ],
-    trigger: '$redo kafka, redo kafka, or /skills then choose redo'
+    trigger: '$redo kafka, redo kafka, or /skills then choose redo',
+    detectors: [
+      {
+        type: 'command',
+        value: 'codex',
+        label: 'codex command'
+      },
+      {
+        type: 'path',
+        value: process.env.CODEX_HOME || path.join(os.homedir(), '.codex'),
+        label: process.env.CODEX_HOME ? 'CODEX_HOME' : '~/.codex'
+      }
+    ],
+    missingReason: 'codex command and Codex CLI home directory were not detected.'
   },
   {
     id: 'claude-code',
@@ -59,7 +81,20 @@ const targets = [
         destination: path.join(os.homedir(), '.claude', 'commands', 'redo.md')
       }
     ],
-    trigger: '/redo kafka'
+    trigger: '/redo kafka',
+    detectors: [
+      {
+        type: 'command',
+        value: 'claude',
+        label: 'claude command'
+      },
+      {
+        type: 'path',
+        value: path.join(os.homedir(), '.claude'),
+        label: '~/.claude'
+      }
+    ],
+    missingReason: 'claude command and Claude Code home directory were not detected.'
   }
 ];
 
@@ -116,21 +151,114 @@ async function ensureSourceSkillExists() {
 }
 
 async function promptTargets() {
+  const detectedTargets = await detectTargets();
+  const availableTargets = detectedTargets.filter((target) => target.available);
+
+  if (availableTargets.length === 0) {
+    console.log(chalk.yellow('No supported AI tools were detected. Nothing installed.'));
+    console.log(chalk.dim('Install Codex, Codex CLI, or Claude Code first, then run this installer again.'));
+    return [];
+  }
+
   const answers = await inquirer.prompt([
     {
       type: 'checkbox',
       name: 'targetIds',
       message: 'Select AI tools to install redo for:',
-      choices: targets.map((target) => ({
-        name: `${target.name} ${chalk.dim('- ' + target.description)}`,
+      choices: detectedTargets.map((target) => ({
+        name: formatTargetChoice(target),
         value: target.id,
-        checked: true
+        checked: target.available,
+        disabled: false
       })),
       validate: (values) => (values.length > 0 ? true : 'Select at least one tool.')
     }
   ]);
 
-  return targets.filter((target) => answers.targetIds.includes(target.id));
+  const selectedTargets = detectedTargets.filter((target) => answers.targetIds.includes(target.id));
+  return promptUndetectedTargetConfirmation(selectedTargets);
+}
+
+async function detectTargets() {
+  return Promise.all(
+    targets.map(async (target) => {
+      const detection = await detectTarget(target);
+      return {
+        ...target,
+        ...detection
+      };
+    })
+  );
+}
+
+async function detectTarget(target) {
+  for (const detector of target.detectors) {
+    if (detector.type === 'path' && (await exists(detector.value))) {
+      return {
+        available: true,
+        detectionLabel: detector.label
+      };
+    }
+
+    if (detector.type === 'command' && (await commandExists(detector.value))) {
+      return {
+        available: true,
+        detectionLabel: detector.label
+      };
+    }
+  }
+
+  return {
+    available: false,
+    detectionLabel: null
+  };
+}
+
+function formatTargetChoice(target) {
+  const description = chalk.dim('- ' + target.description);
+
+  if (target.available) {
+    return `${target.name} ${description} ${chalk.green('(detected: ' + target.detectionLabel + ')')}`;
+  }
+
+  return `${target.name} ${description} ${chalk.yellow('(not detected)')}`;
+}
+
+async function commandExists(command) {
+  const lookupCommand = process.platform === 'win32' ? 'where' : 'which';
+
+  return new Promise((resolve) => {
+    execFile(lookupCommand, [command], (error) => {
+      resolve(!error);
+    });
+  });
+}
+
+async function promptUndetectedTargetConfirmation(selectedTargets) {
+  const confirmedTargets = [];
+
+  for (const target of selectedTargets) {
+    if (target.available) {
+      confirmedTargets.push(target);
+      continue;
+    }
+
+    const destinationSummary = target.tasks.map((task) => task.destination).join(', ');
+    const answers = await inquirer.prompt([
+      {
+        type: 'confirm',
+        name: 'installAnyway',
+        message: `${target.name} was not detected. Install to ${destinationSummary} anyway?`,
+        default: false
+      }
+    ]);
+
+    if (answers.installAnyway) {
+      confirmedTargets.push(target);
+    }
+  }
+
+  return confirmedTargets;
 }
 
 async function promptConflictActions(plan) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@justinforfun/redo-skill",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Install the redo skill for Codex, Codex CLI, and Claude Code.",
   "type": "module",
   "keywords": [

package/skills/redo/README.md

@@ -16,6 +16,8 @@ The installer supports:
 - Codex CLI
 - Claude Code
 
+The installer detects supported tools on the local machine. Detected tools are selected by default; tools that are not detected are left unselected but can still be chosen. If you choose an undetected tool, the installer asks for confirmation before writing to its default directory.
+
 ## Invocation
 
 ```text
@@ -44,6 +46,8 @@ For each technology, `redo` reconstructs:
 - Candidate options and their costs
 - Why the chosen design won
 - Key trade-offs
+- Transferable design patterns in sibling systems
+- Boundary cases and counterexamples
 - Technical debt introduced
 - Debt that was later resolved
 - Pain points that still remain

package/skills/redo/SKILL.md

@@ -36,6 +36,8 @@ redo <topic> [--lang zh|en]
 - `--lang en` forces English output.
 - If `--lang` is absent, respond in the user's current conversation language.
 
+The selected output language applies to the entire answer. Localize every user-facing section name, heading, table label, fixed phrase, and summary label into that language. Do not leak English template labels such as "Stage", "Debt introduced", "One-sentence version", "Transferable Pattern", "Counterexample", or "Sources" unless the user asked for English.
+
 ## Evidence Requirements
 
 For real technologies, do not rely only on memory when dates, versions, authorship, current status, or historical claims matter.
@@ -43,7 +45,10 @@ For real technologies, do not rely only on memory when dates, versions, authorsh
 - If web access is available and the user has not forbidden it, verify with primary or high-authority sources first: official documentation, release notes, RFCs, design docs, papers, project repositories, or authoritative engineering blogs.
 - If web access is unavailable, blocked, or the user forbids browsing, state clearly that the analysis is not freshly verified from online sources.
 - Distinguish sourced facts from inference. It is acceptable to infer engineering motivations, but label them as inference when the source does not explicitly say so.
-- Prefer fewer, stronger stages over many shallow ones. A good answer usually has 5-9 stages.
+- Prefer primary sources over secondary commentary. Good sources include official docs, release notes, KIPs/RFCs/PEPs/design proposals, original papers, maintainers' posts, and authoritative engineering retrospectives.
+- Research relevant papers separately when the topic has an academic or foundational design lineage. Papers often explain why the original abstraction was plausible, what constraints the designers optimized for, and which trade-offs were known from the beginning. Do not only search release notes and blog posts.
+- Avoid weak secondary sources when primary sources exist. Do not cite SEO summaries, generic tutorials, or casual comparison posts for core historical claims if official design docs, papers, or maintainer explanations are available.
+- Avoid source dumping. Cite the key sources used, and when useful, say which stages they support.
 
 ## Output Contract
 
@@ -51,12 +56,30 @@ Start with a compact orientation:
 
 - What the system is.
 - The central pressure that shaped its evolution.
-- The main trade-off theme that appears repeatedly.
+- The one-sentence trade-off theme that appears repeatedly. Make this sharp and reusable, not academic.
 
 Then produce the sections below.
 
 ### 1. Evolution Stages
 
+Choose stages by engineering decision pressure, not by release chronology. Causal order is more important than strict release order, but time should generally move forward. If a later concern appears before an earlier release, explain why the causal dependency is being presented that way.
+
+For mature infrastructure, databases, runtimes, frameworks, languages, and major tools, a good answer usually has 7-9 stages. Do not compress a major "debt repayment" stage into the debt map if it changed how users operate the system. If you use more than 8 stages, the extra stage must earn its place by explaining a current frontier, current user-facing pain, or important debt repayment that would otherwise be invisible.
+
+A stage can be a partial mitigation, not only a new feature. If a prior debt became painful at scale and later received a named fix, protocol change, runtime change, scheduler change, storage change, migration path, or operational redesign, make that fix its own stage. Do not hide it only in the debt map.
+
+For mature systems, check whether the stage list covers these arcs where relevant:
+
+- Prototype or original abstraction.
+- Reliability and replication/fault tolerance.
+- Coordination, metadata, scheduling, ownership, or state management.
+- Semantics/correctness guarantees.
+- Ecosystem or higher-level abstraction.
+- Major mitigation of a previously introduced operational pain.
+- Scale, cloud-native, elasticity, or operations.
+- Cost/storage/performance pressure.
+- Current unresolved frontier.
+
 For each stage, use this structure:
 
 ```markdown
@@ -72,43 +95,118 @@ For each stage, use this structure:
 
 **Key trade-off:** <the most important exchange>
 
-**Debt introduced:** <what this choice made harder later>
+**Debt introduced:** D<N> - <what this choice made harder later>
 ```
 
 Stage quality rules:
 
 - Every stage must be driven by a concrete constraint, not by a release note.
 - Every table must contain at least two rejected options and one chosen path.
-- Explain why a reasonable engineer would choose the winning path at that time, even if it later caused problems.
+- Keep table cells tight: one cost, one reason, one decision. Avoid long essay cells.
+- The chosen option must say why it was rational under the constraints of that stage, even if it later caused problems.
+- The rejected options must be plausible choices real engineers would have considered.
+- The debt line must create a traceable debt ID such as D1, D2, D3. Reuse these IDs in the debt map.
+- Use clean top-level debt IDs: D1, D2, D3, and so on. If one stage introduces multiple meaningful debts, assign the next clean IDs instead of ad-hoc labels such as D2-4 or D3b.
+- When a stage primarily repays earlier debt, explicitly say which debt IDs it repays and what new debt it introduces.
 - Avoid hindsight moralizing. The point is to recreate the decision pressure, not to mock past designs.
 
 ### 2. Throughline
 
-Summarize the recurring design philosophy in one or two paragraphs. Make it specific to the topic, for example:
+Summarize the recurring design philosophy in one or two paragraphs plus a compact table. Make it specific to the topic, for example:
 
 - "Push complexity into the runtime to keep application code simple."
 - "Preserve backward compatibility even when it complicates internals."
 - "Use logs as the universal abstraction."
 
-### 3. Debt Map
+Then add:
 
-Create two tables.
+```markdown
+| Repeated choice | What it avoided | What it made harder | Outcome |
+|---|---|---|---|
+```
 
-Resolved debt:
+Use this structure so the section is stable:
 
 ```markdown
-| Debt | Introduced in | Resolved in | Resolution |
+## Throughline
+
+<one paragraph naming the recurring philosophy>
+
+The cost: <one sentence naming the recurring price>
+
+| Repeated choice | What it avoided | What it made harder | Outcome |
 |---|---|---|---|
+
+**Design-review sentence:** "<one memorable sentence>"
 ```
 
-Unresolved debt:
+### 3. Transferable Pattern and Boundaries
+
+After the throughline, add a section that helps the reader generalize the core design idea beyond the topic. This is not a random "similar tools" list. It should identify the reusable engineering philosophy, show where other systems apply the same idea, and show where the idea breaks down.
+
+Use this structure:
 
 ```markdown
-| Pain point | Why it remains hard | Current manifestation |
+## Transferable Pattern
+
+<one paragraph naming the reusable idea, such as "delegate caching to the operating system", "make the log the source of truth", or "push coordination into a control plane">
+
+| System | How it uses the same idea | Shared constraint | Different price |
+|---|---|---|---|
+| <system> | <specific mechanism> | <why the same idea fits> | <what this system pays instead> |
+```
+
+Then add a boundary or counterexample table:
+
+```markdown
+## Where This Pattern Stops
+
+| Counterexample | Why the opposite choice is rational | Boundary rule |
 |---|---|---|
+| <system or system class> | <mechanism-level reason> | <when not to copy the original topic's design> |
 ```
 
-### 4. Pain Point Ranking
+Generalization quality rules:
+
+- Compare mechanisms, not product categories. "Both rely on OS page cache for immutable segment-like files" is useful; "both are data systems" is not.
+- Include 3-5 sibling systems when there is a real shared principle. If fewer than 3 are defensible, use fewer and explain why.
+- Include at least one counterexample or boundary class when the pattern has a meaningful opposite design. The counterexample should make the original idea clearer, not just criticize another system.
+- Every sibling or counterexample must name the condition that makes the design work or fail: immutable files, append-only logs, random updates, strict transaction control, latency tail sensitivity, memory ownership, coordination scope, compatibility pressure, and so on.
+- Do not imply the original topic's design is universally superior. The goal is "when to copy this idea" and "when not to copy it".
+- For specific comparisons to real systems, verify with primary or high-authority sources when online verification is available.
+
+### 4. Debt Map
+
+Create three tables. Use the debt IDs introduced in the stages. A debt is "resolved" only when the original failure mode is structurally removed or no longer a normal user concern. If a later design reduces blast radius, frequency, or operational cost but the pain can still appear, put it under "mitigated", not "resolved".
+
+Resolved debt:
+
+```markdown
+| Debt ID | Debt | Introduced in | Resolved in | Resolution |
+|---|---|---|---|---|
+```
+
+Mitigated debt:
+
+```markdown
+| Debt ID | Debt | Introduced in | Mitigated in | What improved | What remains |
+|---|---|---|---|---|---|
+```
+
+Unresolved debt:
+
+```markdown
+| Debt ID | Pain point | Why it remains hard | Current manifestation |
+|---|---|---|---|
+```
+
+Debt map quality rules:
+
+- The map must explain "introduced in stage X, resolved or mitigated in stage Y" where applicable.
+- Do not list only abstract categories like "operational complexity". Name the concrete failure mode users feel.
+- Include important unresolved operational pain even if it came from an omitted or secondary stage, but label it clearly.
+
+### 5. Pain Point Ranking
 
 Rank the top unresolved problems that users still feel today.
 
@@ -119,24 +217,99 @@ Rank the top unresolved problems that users still feel today.
 
 Use the competitive attack angle only when there is a meaningful comparison. Otherwise write "N/A".
 
-### 5. Causal Chain
+Ranking quality rules:
+
+- Prefer production symptoms over abstract labels: "rebalance storms", "cold-read latency", "schema migration pain", "dependency hell", "slow compile times", "state restore time", "version skew".
+- The one-line explanation should describe what users observe during failure or scale, not just why the architecture is complex.
+- Competitive attack angles should be concrete. Name a class of alternative system or a known competitor only when the comparison is fair.
+- Do not overclaim in competitive comparisons. If an alternative avoids one pain by accepting another trade-off, state that trade-off briefly instead of implying it is strictly better.
+- Phrase attack angles as trade-off-aware comparisons: "X can attack this by doing Y, but pays Z." Avoid claims like "X does not have this problem" unless a primary source or well-established mechanism supports it.
+- If the comparison would be shallow or unfair, write "N/A" rather than forcing a competitor into the table.
+
+### 6. Causal Chain
+
+End with a causal chain that makes the evolution memorable. For complex systems, use an ASCII story map rather than a flat paragraph:
+
+```text
+early constraint -> chosen design -> solved problem, but introduced D<N>
+     |
+     v
+next constraint -> next design -> repaid D<N>, but introduced D<M>
+```
+
+Keep it concise and legible. The best chain should let the reader retell the system's history from memory.
 
-End with a causal chain that makes the evolution memorable:
+Use arrows and vertical continuation when it improves readability:
 
 ```text
-early constraint -> chosen design -> solved problem -> new debt -> later fix -> remaining pain
+2011 original constraint -> 2012 design -> solved X, but introduced D1
+     |
+     v
+2014 next constraint -> next design -> repaid D1, but introduced D2
+```
+
+After the chain, add a bold one-sentence version:
+
+```markdown
+**One-sentence version:** <the system's repeated pattern and unresolved tension today>
 ```
 
-Keep it concise and legible.
+This sentence should be conversational, sharp, and technically accurate.
+
+### 7. Sources
+
+If online verification was used, end with a short source list. Prefer 6-10 high-signal sources over a long bibliography. Split sources into primary and secondary groups. Use secondary sources only when they add useful synthesis or operational perspective, and keep them to at most two items. Do not use a secondary source for a core mechanism when an official design doc, release note, RFC, KIP, PEP, paper, or maintainer explanation exists.
+
+Use this format:
+
+```markdown
+Primary sources:
+
+- Foundational papers: <source>
+- Stage 2 replication: <source>
+- Stage 5 correctness semantics: <source>
+- Current pain points: <source>
+
+Secondary sources (optional, max 2):
+
+- Operational retrospective or synthesis: <source>
+```
+
+Source quality rules:
+
+- Every major stage should be supported by at least one primary source when online verification is available.
+- If an important claim is inferred from multiple sources rather than directly stated, mark it as inference in the analysis.
+- Do not cite generic tutorials, SEO summaries, or casual comparison posts for mechanism, history, or version claims.
+
+Do not let sources replace reasoning. The main output should remain the decision tree and debt map.
 
 ## Style
 
 - Write like a senior engineer explaining architecture history to another engineer.
+- Keep the language conversational but precise: sound like a senior engineer explaining the decision in a design review, not like a paper abstract or a marketing article.
+- Prefer memorable engineering phrasing over neutral summaries, but never sacrifice technical accuracy for punchlines.
 - Prefer concrete mechanisms, failure modes, and operational consequences.
+- Make the answer feel like a decision tree and a debt map, not a neutral research report.
 - Use direct language. Avoid vague praise such as "powerful", "robust", or "revolutionary" unless immediately explained.
 - Use Chinese if the user is writing Chinese, English if the user is writing English, unless `--lang` overrides.
 - If the topic is too broad, choose the core system path and say what you intentionally left out.
 - If the historical record is uncertain, say so and give the most likely interpretation.
+- Match the output language consistently. For non-English output, translate headings and table labels into the user's language instead of leaking English template labels.
+
+## Quality Gate
+
+Before finalizing, check the answer against these questions:
+
+- Could a reader infer the system's evolution from stage 1 to today by following only the trade-offs?
+- Did you include major debt repayment stages, not just feature releases?
+- Did you include major partial-mitigation stages when a painful debt later received an important fix?
+- Does every stage have plausible rejected alternatives and a rational chosen path?
+- Are the pain points concrete production symptoms rather than broad categories?
+- Does every resolved or unresolved debt connect back to a stage or debt ID?
+- Is the throughline sharp enough to quote in one sentence?
+- Does the transferable-pattern section show where the core idea works in other systems and where it stops?
+- Are sources high-signal and tied to the claims they support?
+- Is the language of headings, labels, and section names consistent with the user's language?
 
 ## Tool-Specific Invocation Notes