{"record":{"id":"dd5567e808678032","repo":"gastownhall/beads","slug":"expand-loading-q-w","errorCode":null,"errorMessage":"expand: loading %q: %w","messagePattern":"expand: loading %q: %w","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/formula/expand.go","lineNumber":64,"sourceCode":"\t// Track which steps have been expanded (to avoid double expansion)\n\texpanded := make(map[string]bool)\n\n\t// Apply expand rules first (specific targets)\n\tresult := steps\n\tfor _, rule := range compose.Expand {\n\t\ttargetStep, ok := stepMap[rule.Target]\n\t\tif !ok {\n\t\t\treturn nil, fmt.Errorf(\"expand: target step %q not found\", rule.Target)\n\t\t}\n\n\t\tif expanded[rule.Target] {\n\t\t\tcontinue // Already expanded\n\t\t}\n\n\t\t// Load the expansion formula\n\t\texpFormula, err := parser.LoadByName(rule.With)\n\t\tif err != nil {\n\t\t\treturn nil, fmt.Errorf(\"expand: loading %q: %w\", rule.With, err)\n\t\t}\n\n\t\tif expFormula.Type != TypeExpansion {\n\t\t\treturn nil, fmt.Errorf(\"expand: %q is not an expansion formula (type=%s)\", rule.With, expFormula.Type)\n\t\t}\n\n\t\tif len(expFormula.Template) == 0 {\n\t\t\treturn nil, fmt.Errorf(\"expand: %q has no template steps\", rule.With)\n\t\t}\n\n\t\t// Merge formula default vars with rule overrides\n\t\tvars := mergeVars(expFormula, rule.Vars)\n\n\t\t// Expand the target step (start at depth 0)\n\t\texpandedSteps, err := expandStep(targetStep, expFormula.Template, 0, vars)\n\t\tif err != nil {\n\t\t\treturn nil, fmt.Errorf(\"expand %q: %w\", rule.Target, err)\n\t\t}","sourceCodeStart":46,"sourceCodeEnd":82,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/internal/formula/expand.go#L46-L82","documentation":"ApplyExpansions wraps failures from parser.LoadByName when loading the expansion formula named by a compose.Expand rule's With field. The With value must resolve to a loaded expansion-type formula whose template replaces the target step. This error means the named formula could not be found or parsed, and the load failure is preserved via %w.","triggerScenarios":"Calling ApplyExpansions(steps, compose, parser) where compose.Expand[].With names a formula that is not registered with the parser, does not exist on disk/in the registry, or fails to parse.","commonSituations":"Referencing an expansion formula that was never defined or has a different name; formula file not in the parser's search path; YAML syntax error inside the referenced expansion formula; renaming an expansion formula without updating expand/map rules that use it.","solutions":["Read the wrapped error to see whether the formula was not found or failed to parse","Confirm the With name matches an existing expansion formula (Type: expansion) visible to the parser's search paths","Validate/parse the referenced formula file directly to surface any YAML or schema errors","Update stale With references after renaming expansion formulas"],"exampleFix":"// before\nexpand:\n  - target: review\n    with: revew-checklist\n// after\nexpand:\n  - target: review\n    with: review-checklist","handlingStrategy":"validation","validationCode":"for _, r := range compose.Expand {\n\tf, err := parser.LoadByName(r.With)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"expansion %q unavailable: %w\", r.With, err)\n\t}\n\tif f.Type != TypeExpansion {\n\t\treturn fmt.Errorf(\"%q is type %s, want expansion\", r.With, f.Type)\n\t}\n}","typeGuard":null,"tryCatchPattern":"result, err := ApplyExpansions(steps, compose, parser)\nif err != nil {\n\tvar loadErr error\n\tif _, scanErr := fmt.Sscanf(err.Error(), \"expand: loading %q\", new(any)); scanErr == nil {\n\t\tloadErr = errors.Unwrap(err)\n\t}\n\treturn fmt.Errorf(\"expansion formula load failed: %w\", errors.Join(err, loadErr))\n}","preventionTips":["Verify every With name resolves via parser.LoadByName before applying expansions","Keep referenced expansion formulas on the parser's configured search paths","Parse-check all formula files in CI so broken YAML is caught early","Update With references whenever an expansion formula is renamed"],"tags":["go","formula","expansion","formula-not-found"],"backgroundTag":"formula-load-failed","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}