concept-seed: --mode must be persuade, operate, read, or exp

Error message

concept-seed: --mode must be persuade, operate, read, or experience

What it means

Thrown when --mode is provided but is not one of the four SEED_MODES: persuade, operate, read, experience. Mode names the register of work the requested surface belongs to so appended compositions match; null/undefined means roll from the full approved pool and is allowed.

Source

Thrown at plugin/skills/impeccable/scripts/concept-seed.mjs:322

  _resolvedData = undefined,
} = {}) {
  if (scope !== 'surface' && scope !== 'direction') {
    throw new Error('concept-seed: --scope must be direction or surface');
  }
  if (!Number.isInteger(reroll) || reroll < 0) {
    throw new Error('concept-seed: --reroll must be a non-negative integer');
  }
  if (register !== null && register !== 'safer' && register !== 'bolder') {
    throw new Error('concept-seed: --register must be safer or bolder');
  }
  if (register !== null && reroll < 1) {
    throw new Error('concept-seed: --register steers a re-roll round; pass --reroll <n> with it');
  }
  if (register !== null && scope !== 'direction') {
    throw new Error('concept-seed: --register applies to direction rounds only');
  }
  if (mode !== null && !SEED_MODES.has(mode)) {
    throw new Error('concept-seed: --mode must be persuade, operate, read, or experience');
  }
  // Grain needs no mode: how much of the product is in play is independent of
  // which register of work it is.
  if (grain !== null && !COMPOSITION_GRAINS.includes(grain)) {
    throw new Error(`concept-seed: --grain must be one of ${COMPOSITION_GRAINS.join(', ')}`);
  }
  if (platform !== null && !COMPOSITION_PLATFORMS.includes(platform)) {
    throw new Error(`concept-seed: --platform must be one of ${COMPOSITION_PLATFORMS.join(', ')}`);
  }
  if (!Number.isInteger(candidateCount) || candidateCount < 5 || candidateCount > 7) {
    throw new Error('concept-seed: --candidate-count must be an integer from 5 to 7');
  }
  const unit = (salt) => {
    const h = crypto.createHash('sha256').update(`${scope}:${salt}:${key}`).digest();
    return h.readUInt32BE(0) / 0xffffffff;
  };
  const indexSalt = reroll === 0 ? 'index' : `index:reroll-${reroll}`;
  const buildIndex = 3 + Math.floor(unit(indexSalt) * (candidateCount - 2)); // 3..candidateCount

View on GitHub (pinned to d14711ae3d)

Solutions

Use exactly one of: --mode persuade, --mode operate, --mode read, --mode experience.
Omit --mode to roll compositions from the full approved pool.

Example fix

# before
$ node concept-seed.mjs --scope surface --mode reading ...

# after
$ node concept-seed.mjs --scope surface --mode read ...

Defensive patterns

Strategy: validation

Validate before calling

const SEED_MODES = new Set(['persuade', 'operate', 'read', 'experience']);
if (mode != null && !SEED_MODES.has(mode)) {
  throw new Error(`--mode must be one of: ${[...SEED_MODES].join(', ')}`);
}

Type guard

function isValidMode(value) {
  return value == null || ['persuade','operate','read','experience'].includes(value);
}

Try / catch

try {
  await seedConcepts({ scope, mode });
} catch (err) {
  if (/--mode must be/.test(err.message)) {
    console.error('Use --mode persuade|operate|read|experience, or omit it.');
  } else throw err;
}

Prevention

Parse --mode as an enum at the CLI boundary.
Document the four canonical modes; note that omitting is valid (full pool).
Share the SEED_MODES set between CLI parsing, the seeder, and the validator.

When it happens

Trigger: Passing --mode with a typo or unsupported value ('reading', 'operational', 'sales', 'marketing'). The check is mode !== null && !SEED_MODES.has(mode), where SEED_MODES = {persuade, operate, read, experience}.

Common situations: CLI typo; a wrapper using a domain term instead of the four canonical modes; an outdated caller from before the mode set was fixed.

Related errors

AI-assisted analysis of pbakaus/impeccable@d14711ae3d (2026-08-13). Data as JSON: /api/errors/923d30f684409850. Report an issue: GitHub.