Yeachan-Heo/oh-my-codex · error · UltragoalError

Refusing to derive ${parentItems.length} implicit ultragoal

Error message

Refusing to derive ${parentItems.length} implicit ultragoal goals from ${sourceKind}. Pass compact executable stories with repeated --goal "Title::Objective" entries, or rewrite the brief with an explicit ### Stories/### Goals section containing no more than ${MAX_IMPLICIT_MARKDOWN_GOALS} parent stories.

What it means

assertSafeImplicitMarkdownGoalCount is a guard inside deriveGoalCandidates: when a markdown brief has no explicit `### Stories`/`### Goals` section but its top-level bullet list contains more than MAX_IMPLICIT_MARKDOWN_GOALS parent items, the library refuses to auto-derive goals. This prevents feeding a whole plan/review handoff document (which happens to be markdown with many bullets) into the ultragoal pipeline as if each bullet were a story.

Source

Thrown at src/ultragoal/artifacts.ts:461

}

function hasExplicitStorySection(items: readonly MarkdownListItem[]): boolean {
  return items.some((item) => sectionLooksStory(item.section));
}

function briefLooksPlanLikeHandoff(lines: readonly string[]): boolean {
  return lines.some((line) => {
    const label = normalizeSectionLabel(line);
    if (sectionLooksPlanReview(label)) return true;
    return /\b(?:RALPLAN|G\d{3,}\s+(?:verdict|review|status)|review\s+artifact|consensus\s+status|planner\s+consensus|critic\s+review|architect\s+review)\b/i.test(line);
  });
}

function assertSafeImplicitMarkdownGoalCount(brief: string, parsedItems: readonly MarkdownListItem[], parentItems: readonly MarkdownListItem[]): void {
  if (hasExplicitStorySection(parsedItems)) return;
  if (parentItems.length <= MAX_IMPLICIT_MARKDOWN_GOALS) return;
  const sourceKind = briefLooksPlanLikeHandoff(brief.split(/\r?\n/)) ? 'plan/review handoff markdown' : 'broad markdown';
  throw new UltragoalError(`Refusing to derive ${parentItems.length} implicit ultragoal goals from ${sourceKind}. Pass compact executable stories with repeated --goal "Title::Objective" entries, or rewrite the brief with an explicit ### Stories/### Goals section containing no more than ${MAX_IMPLICIT_MARKDOWN_GOALS} parent stories.`);
}

function normalizeObjective(value: string): string {
  return value.replace(/\s+/g, ' ').trim();
}

const OBJECTIVE_MAPPING_STOP_WORDS = new Set([
  'about',
  'active',
  'aggregate',
  'audit',
  'brief',
  'build',
  'clean',
  'codex',
  'complete',
  'completed',
  'different',

View on GitHub (pinned to 3ad79a8a6f)

Solutions

  1. Add an explicit `### Stories` (or `### Goals`) section to the brief containing at most MAX_IMPLICIT_MARKDOWN_GOALS parent stories
  2. Replace the implicit bullets with repeated explicit --goal "Title::Objective" CLI entries
  3. Trim the brief down to only executable parent stories and move plan/handoff context into a separate reference doc
  4. If the document is really a plan/review handoff, split it: extract the actionable stories first, then pass those

Example fix

// before
// brief.md: 40 top-level bullets of plan/review notes, no Stories heading
deriveGoalCandidates(briefMarkdown); // refuses

// after
// brief.md:
// ### Stories
// - Fix login redirect::Redirect after OAuth callback
// - Add rate limit::Cap API at 100 req/min
deriveGoalCandidates(briefMarkdown); // ok
Defensive patterns

Strategy: validation

Validate before calling

const STORY_HEADING = /^#{2,3}\s*(Stories|Goals)\b/m;

function briefIsSafeForImplicitDerivation(brief: string, maxParentItems = MAX_IMPLICIT_MARKDOWN_GOALS): boolean {
  if (STORY_HEADING.test(brief)) return true; // explicit section bypasses the guard
  const parentItems = brief.split(/\r?\n/).filter((l) => /^[-*+]\s+/.test(l) && !/^\s/.test(l));
  return parentItems.length <= maxParentItems;
}

Type guard

function isImplicitGoalCountError(e: unknown): boolean {
  return e instanceof UltragoalError && /implicit ultragoal goals/.test(e.message);
}

Try / catch

try {
  deriveGoalCandidates(brief);
} catch (e) {
  if (isImplicitGoalCountError(e)) {
    // restructure brief: add ### Stories section or switch to explicit --goal entries
  } else throw e;
}

Prevention

When it happens

Trigger: Calling deriveGoalCandidates (or the ultragoal CLI deriving goals) with a markdown brief that (a) lacks an explicit Stories/Goals heading and (b) has more than MAX_IMPLICIT_MARKDOWN_GOALS top-level list items. briefLooksPlanLikeHandoff further classifies it, but the refusal happens regardless of that classification once the count is exceeded.

Common situations: Pasting a full implementation plan, PR review, or meeting-notes document as the brief instead of compact stories; using one big markdown file for everything; migrating from a tool that accepted arbitrary markdown briefs; hallucinating that the AI will 'figure out' the story decomposition from a wall of bullets.

Related errors

AI-assisted analysis of Yeachan-Heo/oh-my-codex@3ad79a8a6f (2026-08-27). Data as JSON: /api/errors/e7f854ccc65aa4c6. Report an issue: GitHub.