Skip to content

ShipfoxHQ/shipfox / .github/skills/impeccable

impeccable

Flagged

Use when the user wants to design, redesign, shape, critique, audit, polish, clarify, distill, harden, optimize, adapt, animate, colorize, extract, or otherwise improve a frontend interface. Covers websites, landing pages, dashboards, product UI, app shells, components, forms, settings, onboarding, and empty states. Handles UX review, visual hierarchy, information architecture, cognitive load, accessibility, performance, responsive behavior, theming, anti-patterns, typography, fonts, spacing, layout, alignment, color, motion, micro-interactions, UX copy, error states, edge cases, i18n, and reusable design systems or tokens. Also use for bland designs that need to become bolder or more delightful, loud designs that should become quieter, live browser iteration on UI elements, or ambitious visual effects that should feel technically extraordinary. Not for backend-only or non-UI tasks.

FileKindSize
SKILL.mdskill md10.4 KB
reference/adapt.mdmarkdown10.1 KB
reference/adapt.native.mdmarkdown3.8 KB
reference/android.mdmarkdown3.2 KB
reference/animate.mdmarkdown4.7 KB
reference/audit.mdmarkdown7.7 KB
reference/audit.native.mdmarkdown8.2 KB
reference/bolder.mdmarkdown3.1 KB
reference/clarify.mdmarkdown4.5 KB
reference/colorize.mdmarkdown4.4 KB
reference/craft-floor.mdmarkdown3.7 KB
reference/craft.mdmarkdown555 B
reference/critique.mdmarkdown39.0 KB
reference/delight.mdmarkdown3.6 KB
reference/distill.mdmarkdown5.5 KB
reference/doctor.mdmarkdown4.6 KB
reference/document.mdmarkdown26.8 KB
reference/extract.mdmarkdown3.3 KB
reference/harden.mdmarkdown8.3 KB
reference/hooks.mdmarkdown11.6 KB
reference/init.mdmarkdown8.6 KB
reference/ios.mdmarkdown2.9 KB
reference/layout.mdmarkdown5.0 KB
reference/live-setup.mdmarkdown7.2 KB
reference/live.mdmarkdown34.8 KB
reference/new-work.mdmarkdown27.2 KB
reference/onboard.mdmarkdown7.6 KB
reference/operate.mdmarkdown4.0 KB
reference/optimize.mdmarkdown7.4 KB
reference/overdrive.mdmarkdown8.6 KB
reference/polish.mdmarkdown5.1 KB
reference/quieter.mdmarkdown4.7 KB
reference/routing.mdmarkdown2.8 KB
reference/shape.mdmarkdown3.5 KB
reference/typeset.mdmarkdown5.1 KB
reference/visualize.mdmarkdown10.2 KB
scripts/command-metadata.jsonconfig7.7 KB
scripts/concept-seed.mjsscript27.0 KB
scripts/context-signals.mjsscript14.0 KB
scripts/context.mjsscript58.4 KB
scripts/critique-storage.mjsscript7.9 KB
scripts/detect-csp.mjsscript6.6 KB
scripts/detect.mjsscript620 B
scripts/detector/browser/injected/index.mjsscript79.6 KB
scripts/detector/cli/main.mjsscript18.8 KB
scripts/detector/design-system.mjsscript34.3 KB
scripts/detector/detect-antipatterns-browser.jsscript358.1 KB
scripts/detector/detect-antipatterns.mjsscript1.8 KB
scripts/detector/engines/browser/detect-url.mjsscript14.1 KB
scripts/detector/engines/regex/detect-text.mjsscript34.5 KB
scripts/detector/engines/static-html/css-cascade.mjsscript42.7 KB
scripts/detector/engines/static-html/detect-html.mjsscript11.7 KB
scripts/detector/engines/visual/screenshot-contrast.mjsscript6.4 KB
scripts/detector/findings.mjsscript766 B
scripts/detector/node/file-system.mjsscript7.6 KB
scripts/detector/profile/profiler.mjsscript4.4 KB
scripts/detector/registry/antipatterns.mjsscript27.2 KB
scripts/detector/rules/checks.mjsscript246.3 KB
scripts/detector/shared/color.mjsscript4.4 KB
scripts/detector/shared/constants.mjsscript4.6 KB
scripts/detector/shared/fonts.mjsscript852 B
scripts/detector/shared/inline-ignores.mjsscript6.0 KB
scripts/detector/shared/page.mjsscript252 B
scripts/doctor.mjsscript11.6 KB
scripts/embed-prompt.mjsscript5.8 KB
scripts/generate-image.mjsscript9.6 KB
scripts/hook-admin.mjsscript28.4 KB
scripts/hook-before-edit.mjsscript18.3 KB
scripts/hook-lib.mjsscript81.4 KB
scripts/hook.mjsscript2.6 KB
scripts/lib/artifact-schema.mjsscript3.8 KB
scripts/lib/composition-catalog.mjsscript10.0 KB
scripts/lib/concept-catalog.mjsscript17.4 KB
scripts/lib/design-parser.mjsscript25.2 KB
scripts/lib/impeccable-config.mjsscript22.2 KB
scripts/lib/impeccable-paths.mjsscript4.9 KB
scripts/lib/is-generated.mjsscript2.2 KB
scripts/lib/provider.mjsscript327 B
scripts/lib/roll-selection.mjsscript16.9 KB
scripts/lib/staleness-deep.mjsscript19.6 KB
scripts/lib/staleness-notice.mjsscript6.5 KB
scripts/lib/staleness.mjsscript19.0 KB
scripts/lib/surface-briefs.mjsscript6.1 KB
scripts/lib/target-args.mjsscript1.1 KB
scripts/lib/target-slug.mjsscript1.0 KB
scripts/lib/template-extensions.mjsscript5.3 KB
scripts/live-accept.mjsscript35.5 KB
scripts/live-browser-dom.jsscript4.2 KB
scripts/live-browser-session.jsscript3.2 KB
scripts/live-browser.jsscript489.1 KB
scripts/live-commit-manual-edits.mjsscript41.2 KB
scripts/live-complete.mjsscript4.7 KB
scripts/live-copy-edit-agent.mjsscript28.2 KB
scripts/live-discard-manual-edits.mjsscript1.6 KB
scripts/live-inject.mjsscript18.1 KB
scripts/live-insert.mjsscript9.8 KB
scripts/live-manual-edit-evidence.mjsscript11.6 KB
scripts/live-poll.mjsscript15.7 KB
scripts/live-resume.mjsscript6.0 KB
scripts/live-server.mjsscript66.1 KB
scripts/live-status.mjsscript2.6 KB
scripts/live-target.mjsscript934 B
scripts/live-wrap.mjsscript38.2 KB
scripts/live.mjsscript13.1 KB
scripts/live/accept-css.mjsscript22.0 KB
scripts/live/accept-verify.mjsscript2.7 KB
scripts/live/browser-script-parts.mjsscript2.1 KB
scripts/live/completion.mjsscript1.4 KB
scripts/live/event-validation.mjsscript9.4 KB
scripts/live/frameworks/astro.mjsscript1.7 KB
scripts/live/frameworks/detect-utils.mjsscript2.1 KB
scripts/live/frameworks/index.mjsscript5.7 KB
scripts/live/frameworks/journal.mjsscript7.0 KB
scripts/live/frameworks/nextjs.mjsscript1.7 KB
scripts/live/frameworks/nuxt.mjsscript5.1 KB
scripts/live/frameworks/script-src.mjsscript699 B
scripts/live/frameworks/static-html.mjsscript656 B
scripts/live/frameworks/sveltekit.mjsscript1.8 KB
scripts/live/frameworks/tag-strategy.mjsscript10.6 KB
scripts/live/frameworks/tanstack-start.mjsscript1.6 KB
scripts/live/frameworks/vite-generic.mjsscript1.3 KB
scripts/live/generation-preflight.mjsscript5.8 KB
scripts/live/insert-ui.mjsscript15.3 KB
scripts/live/instructions.mjsscript12.9 KB
scripts/live/manual-apply.mjsscript34.1 KB
scripts/live/manual-edit-routes.mjsscript14.6 KB
scripts/live/manual-edits-buffer.mjsscript5.0 KB
scripts/live/poll-lanes.mjsscript759 B
scripts/live/roots.mjsscript20.4 KB
scripts/live/session-store.mjsscript22.4 KB
scripts/live/source-lock.mjsscript3.6 KB
scripts/live/source-search.mjsscript4.2 KB
scripts/live/svelte-ast.mjsscript37.7 KB
scripts/live/svelte-component.mjsscript49.6 KB
scripts/live/sveltekit-adapter.mjsscript11.1 KB
scripts/live/tanstack-adapter.mjsscript9.5 KB
scripts/live/ui-core.mjsscript5.4 KB
scripts/live/vocabulary.mjsscript7.0 KB
scripts/modern-screenshot.umd.jsscript28.6 KB
scripts/palette.mjsscript55.5 KB
scripts/pin.mjsscript6.3 KB
scripts/serve-question.mjsscript60.2 KB
scripts/surface-brief.mjsscript2.5 KB

scripts/doctor.mjs

View on GitHub
#!/usr/bin/env node
/**
 * Deep staleness pass over Impeccable's own project artifacts.
 *
 *   node doctor.mjs                 # human-readable report
 *   node doctor.mjs --json          # machine-readable, for the skill command
 *   node doctor.mjs --fix           # apply the mechanical migrations only
 *   node doctor.mjs --target <path> # pick a monorepo workspace
 *
 * The boot check in context.mjs reports what a session can afford to measure.
 * This runs everything: git drift, per-workspace sweep, ignore-list validation
 * against the live rule registry, hook script resolution.
 *
 * `--fix` is deliberately narrow. It performs only the migrations marked
 * severity 'auto', the ones with no judgment in them: stamp the product record,
 * move a sidecar out of a retired location. Anything that needs an answer from
 * the user (a platform value, whether an inherited record still describes an
 * app, whether a document has drifted from the code) is reported and left
 * alone. Exit code is 0 unless the run itself failed; findings are not errors.
 */

import fs from 'node:fs';
import path from 'node:path';
import { fileURLToPath } from 'node:url';

import { loadContext, extractPlatform, resolveTargetSelection } from './context.mjs';
import { parseTargetOptions } from './lib/target-args.mjs';
import { IMPECCABLE_COMMAND, IMPECCABLE_PROVIDER_ID } from './lib/provider.mjs';
import { parseDesignMd } from './lib/design-parser.mjs';
import {
  PRODUCT_SCHEMA_VERSION,
  readProductSchemaVersion,
  stampProductSchema,
} from './lib/artifact-schema.mjs';
import {
  checkConfig,
  checkDesignSidecar,
  checkNativePlatformEvidence,
  checkProduct,
  checkProjectRoots,
  checkSurfaceBriefs,
  designSidecarCandidatesFor,
} from './lib/staleness.mjs';
import {
  checkDesignCoverage,
  checkDesignDrift,
  checkDetectorIgnores,
  checkHookInstallation,
  checkLegacyLiveState,
  checkWorkspaces,
  loadKnownRuleIds,
} from './lib/staleness-deep.mjs';

const SCRIPTS_DIR = path.dirname(fileURLToPath(import.meta.url));

function safeRead(filePath) {
  try {
    return fs.readFileSync(filePath, 'utf-8');
  } catch {
    return null;
  }
}

function parseArgs(argv) {
  const passthrough = [];
  const flags = { json: false, fix: false, help: false };
  for (const arg of argv) {
    if (arg === '--json') flags.json = true;
    else if (arg === '--fix') flags.fix = true;
    else if (arg === '--help' || arg === '-h') flags.help = true;
    else passthrough.push(arg);
  }
  return { flags, targetOptions: parseTargetOptions(passthrough, { strict: true }) };
}

function usage() {
  return [
    `Usage: node doctor.mjs [--json] [--fix] [--target <path>]`,
    '',
    "Report drift between this project's Impeccable artifacts and what the",
    'installed version reads: PRODUCT.md, DESIGN.md and its sidecar,',
    '.impeccable/config.json, surface briefs, and the design hook.',
    '',
    '  --json           Emit findings as JSON.',
    '  --fix            Apply the mechanical migrations (severity "auto") only.',
    '  --target <path>  Select a workspace in a monorepo.',
  ].join('\n');
}

async function collect(cwd, targetOptions) {
  const ctx = loadContext(cwd, targetOptions);
  const projectRoot = ctx.projectRoot || cwd;
  const absProductPath = ctx.productPath ? path.resolve(cwd, ctx.productPath) : null;
  const absDesignPath = ctx.designPath ? path.resolve(cwd, ctx.designPath) : null;
  const sidecarCandidates = designSidecarCandidatesFor(projectRoot, ctx.contextDir);
  const knownRuleIds = await loadKnownRuleIds(SCRIPTS_DIR);

  const selection = resolveTargetSelection(cwd, targetOptions);
  const workspaceCandidates = selection?.targetCandidates || [];

  const workspaceResult = checkWorkspaces({
    repoRoot: ctx.repoRoot,
    candidates: workspaceCandidates,
    checkNativePlatformEvidence,
    extractPlatform,
    readFile: safeRead,
  });

  const findings = [
    ...checkProduct(ctx.product, ctx.productPath || 'PRODUCT.md'),
    ...(ctx.product
      ? checkNativePlatformEvidence({
          projectRoot,
          platform: ctx.platform,
          product: ctx.product,
          productPath: ctx.productPath,
        })
      : []),
    ...checkDesignSidecar({ designPath: absDesignPath, sidecarCandidates, projectRoot }),
    ...checkDesignDrift({ designPath: absDesignPath, projectRoot }),
    ...checkDesignCoverage({ design: ctx.design, designPath: ctx.designPath, parseDesignMd }),
    ...checkConfig({ projectRoot, repoRoot: ctx.repoRoot }),
    ...checkDetectorIgnores({ projectRoot, knownRuleIds }),
    ...checkSurfaceBriefs({ candidates: ctx.surfaceBriefCandidates, projectRoot }),
    ...checkHookInstallation({
      projectRoot,
      repoRoot: ctx.repoRoot,
      providerId: IMPECCABLE_PROVIDER_ID,
    }),
    ...checkLegacyLiveState({ projectRoot }),
    ...checkProjectRoots({
      patterns: readProjectRootPatterns(ctx.repoRoot),
      candidates: workspaceCandidates,
    }),
    ...workspaceResult.findings,
  ];

  return {
    ctx,
    projectRoot,
    absProductPath,
    sidecarCandidates,
    findings,
    workspaces: workspaceResult.workspaces,
    ruleRegistryAvailable: knownRuleIds !== null,
  };
}

// Read straight from disk rather than importing context.mjs's private reader.
// Only the positive/negative pattern strings matter here.
function readProjectRootPatterns(repoRoot) {
  if (!repoRoot) return [];
  const patterns = [];
  for (const name of ['config.json', 'config.local.json']) {
    try {
      const raw = JSON.parse(fs.readFileSync(path.join(repoRoot, '.impeccable', name), 'utf-8'));
      if (Array.isArray(raw?.projectRoots)) {
        for (const entry of raw.projectRoots) {
          if (typeof entry === 'string' && entry.trim()) patterns.push(entry.trim());
        }
      }
    } catch { /* missing or malformed: nothing to check */ }
  }
  return patterns;
}

/**
 * Apply the migrations that carry no decision. Returns what was done and what
 * was deliberately left for the user.
 */
function applyFixes(report) {
  const applied = [];
  const skipped = [];

  for (const entry of report.findings) {
    if (entry.severity !== 'auto') {
      skipped.push({ id: entry.id, reason: 'needs a decision from the user' });
      continue;
    }
    if (entry.id === 'design-sidecar-legacy-path') {
      const canonical = report.sidecarCandidates[0];
      const present = report.sidecarCandidates.find((candidate) => fs.existsSync(candidate));
      if (!canonical || !present || path.resolve(canonical) === path.resolve(present)) continue;
      if (fs.existsSync(canonical)) {
        skipped.push({ id: entry.id, reason: `${rel(canonical, report.projectRoot)} already exists; not overwriting` });
        continue;
      }
      fs.mkdirSync(path.dirname(canonical), { recursive: true });
      fs.renameSync(present, canonical);
      applied.push(`Moved ${rel(present, report.projectRoot)} to ${rel(canonical, report.projectRoot)}.`);
      continue;
    }
    if (entry.id === 'legacy-live-state') {
      // Reported, never deleted here: a running live session still reads these,
      // and losing session state to a doctor run is a worse outcome than a
      // stale file. The report says what to remove and when.
      skipped.push({ id: entry.id, reason: 'delete by hand once no live session is running' });
      continue;
    }
    skipped.push({ id: entry.id, reason: 'no automatic migration implemented' });
  }

  // Stamping the product record is additive and safe, and it is what stops a
  // later version proposing an interview the user has already sat through.
  const productPath = report.absProductPath;
  if (productPath && report.ctx.product && readProductSchemaVersion(report.ctx.product) === null
    && !report.findings.some((entry) => entry.id === 'product-schema-legacy')) {
    fs.writeFileSync(productPath, stampProductSchema(report.ctx.product), 'utf-8');
    applied.push(`Stamped ${rel(productPath, report.projectRoot)} as product-schema ${PRODUCT_SCHEMA_VERSION}.`);
  }

  return { applied, skipped };
}

function rel(filePath, root) {
  const value = path.relative(root, filePath);
  return value && !value.startsWith('..') ? value.split(path.sep).join('/') : filePath;
}

const SEVERITY_LABEL = {
  auto: 'automatic',
  mention: 'worth saying',
  route: 'needs a command',
};

function renderText(report, fixes) {
  const lines = [];
  const { findings } = report;

  lines.push(`Impeccable doctor: ${rel(report.projectRoot, process.cwd()) || '.'}`);
  if (report.ctx.isMonorepo) {
    lines.push(`Monorepo, repo root ${rel(report.ctx.repoRoot, process.cwd()) || '.'}.`);
  }
  lines.push('');

  if (!findings.length) {
    lines.push('No drift found. Every artifact matches what this version reads.');
  } else {
    const order = ['route', 'mention', 'auto'];
    for (const severity of order) {
      const group = findings.filter((entry) => entry.severity === severity);
      if (!group.length) continue;
      lines.push(`${SEVERITY_LABEL[severity]} (${group.length}):`);
      for (const entry of group) {
        lines.push(`  ${entry.id}${entry.path ? `  [${entry.path}]` : ''}`);
        lines.push(`    ${entry.summary}`);
        lines.push(`    → ${entry.fix}`);
      }
      lines.push('');
    }
  }

  if (report.workspaces.length) {
    lines.push('Workspaces:');
    for (const workspace of report.workspaces) {
      lines.push(`  ${workspace.path}  product: ${workspace.productStatus}`
        + `  design: ${workspace.designStatus}`
        + `${workspace.platform ? `  platform: ${workspace.platform}` : ''}`);
    }
    lines.push('');
  }

  if (!report.ruleRegistryAvailable) {
    lines.push('Note: the bundled detector could not be resolved, so ignored rule ids were not validated.');
    lines.push('');
  }

  if (fixes) {
    lines.push(fixes.applied.length ? 'Applied:' : 'Applied nothing.');
    for (const entry of fixes.applied) lines.push(`  ${entry}`);
    const held = fixes.skipped.filter((entry) => entry.reason !== 'needs a decision from the user');
    if (held.length) {
      lines.push('Left alone:');
      for (const entry of held) lines.push(`  ${entry.id}: ${entry.reason}`);
    }
  } else if (findings.some((entry) => entry.severity === 'auto')) {
    lines.push(`Run \`node doctor.mjs --fix\` to apply the automatic migrations, `
      + `or \`${IMPECCABLE_COMMAND} doctor\` to work through all of them.`);
  }

  return lines.join('\n');
}

async function cli() {
  let parsed;
  try {
    parsed = parseArgs(process.argv.slice(2));
  } catch (err) {
    process.stderr.write(`${err.message}\n`);
    process.exit(1);
  }
  if (parsed.flags.help) {
    process.stdout.write(`${usage()}\n`);
    return;
  }

  const report = await collect(process.cwd(), parsed.targetOptions);
  const fixes = parsed.flags.fix ? applyFixes(report) : null;

  if (parsed.flags.json) {
    process.stdout.write(`${JSON.stringify({
      projectRoot: report.projectRoot,
      repoRoot: report.ctx.repoRoot,
      isMonorepo: report.ctx.isMonorepo,
      productPath: report.ctx.productPath,
      designPath: report.ctx.designPath,
      platform: report.ctx.platform,
      ruleRegistryAvailable: report.ruleRegistryAvailable,
      findings: report.findings,
      workspaces: report.workspaces,
      ...(fixes ? { fixes } : {}),
    }, null, 2)}\n`);
    return;
  }

  process.stdout.write(`${renderText(report, fixes)}\n`);
}

function invokedAsScript() {
  const arg = process.argv[1];
  if (!arg) return false;
  try {
    return fs.realpathSync(arg) === fs.realpathSync(fileURLToPath(import.meta.url));
  } catch {
    return false;
  }
}

if (invokedAsScript()) {
  cli().catch((err) => {
    process.stderr.write(`impeccable doctor failed: ${err?.message || err}\n`);
    process.exit(1);
  });
}

export { collect, applyFixes, renderText };
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall