{"record":{"id":"87e7635aaede032e","repo":"larksuite/cli","slug":"s-params-requires-agent-readable-when-text","errorCode":null,"errorMessage":"%s.Params requires agent-readable When text","messagePattern":"(.+?)\\.Params requires agent-readable When text","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"shortcuts/common/typed_compile_contract.go","lineNumber":64,"sourceCode":"\t\t\tcompiled.fields = append(compiled.fields, field)\n\t\t}\n\t\tkeyBytes, _ := json.Marshal(definition)\n\t\tkey := string(keyBytes)\n\t\tif _, duplicate := seen[key]; duplicate {\n\t\t\treturn nil, fmt.Errorf(\"Input.Relations[%d] duplicates an earlier relation\", i)\n\t\t}\n\t\tseen[key] = struct{}{}\n\t\tresult = append(result, compiled)\n\t}\n\treturn result, nil\n}\n\nfunc compileAuthorization(definition typedAuthorizationDefinition, fields []compiledInputField, fieldByName map[string]int) error {\n\tfor identity, authorization := range definition.Identities {\n\t\tfor i, conditional := range authorization.ConditionalScopes {\n\t\t\tpath := fmt.Sprintf(\"Authorization.%s.ConditionalScopes[%d]\", identity, i)\n\t\t\tif len(conditional.Params) > 0 && conditional.When == \"\" {\n\t\t\t\treturn fmt.Errorf(\"%s.Params requires agent-readable When text\", path)\n\t\t\t}\n\t\t\tseen := make(map[string]struct{}, len(conditional.Params))\n\t\t\tfor j, param := range conditional.Params {\n\t\t\t\tif param == \"\" || param != strings.TrimSpace(param) {\n\t\t\t\t\treturn fmt.Errorf(\"%s.Params[%d] must be a non-blank trimmed param\", path, j)\n\t\t\t\t}\n\t\t\t\tfieldIndex, ok := fieldByName[param]\n\t\t\t\tif !ok {\n\t\t\t\t\treturn fmt.Errorf(\"%s references unknown param --%s\", path, param)\n\t\t\t\t}\n\t\t\t\tif fields[fieldIndex].cli.Hidden {\n\t\t\t\t\treturn fmt.Errorf(\"%s references hidden param --%s; use a public canonical param\", path, param)\n\t\t\t\t}\n\t\t\t\tif _, duplicate := seen[param]; duplicate {\n\t\t\t\t\treturn fmt.Errorf(\"%s.Params contains duplicate param --%s\", path, param)\n\t\t\t\t}\n\t\t\t\tseen[param] = struct{}{}\n\t\t\t}","sourceCodeStart":46,"sourceCodeEnd":82,"githubUrl":"https://github.com/larksuite/cli/blob/7fd6ef3c07182257ce776cdc5a614e122d5bd4b3/shortcuts/common/typed_compile_contract.go#L46-L82","documentation":"Thrown when a conditional scope entry in Authorization.<identity>.ConditionalScopes declares Params but its When text is empty. Params narrow when a conditional scope applies, so an agent-readable When condition is mandatory to explain the requirement to AI agents and humans.","triggerScenarios":"Defining ConditionalScopes[{Params: [\"--x\"], When: \"\"}] — params present, When omitted or blank.","commonSituations":"Filling in Params and leaving When for later; scaffolding a new conditional scope; stripping When text during a refactor.","solutions":["Write a concise agent-readable When sentence explaining when the params are required","Remove the Params entries if no condition is actually needed"],"exampleFix":"// before\nConditionalScopes: []ConditionalScope{{Params: []string{\"--doc-id\"}}}\n// after\nConditionalScopes: []ConditionalScope{{Params: []string{\"--doc-id\"}, When: \"required when --doc-id targets a wiki document instead of a drive file\"}}","handlingStrategy":"validation","validationCode":"for _, cs := range scope.ConditionalScopes {\n  if len(cs.Params) > 0 && strings.TrimSpace(cs.When) == \"\" {\n    return fmt.Errorf(\"conditional scope with params needs When text\")\n  }\n}","typeGuard":null,"tryCatchPattern":"if err := common.CompileTypedDefinition(def); err != nil {\n  return fmt.Errorf(\"conditional scope misconfigured: %w\", err)\n}","preventionTips":["Write When text at the same time you add Params — never leave a TODO","Review authorization blocks for agent readability in code review","Make a lint/test that fails on empty When with params"],"tags":["go","authorization","scopes","validation"],"backgroundTag":"shortcut-definition-validation-failed","analyzedSha":"7fd6ef3c07182257ce776cdc5a614e122d5bd4b3","analyzedAt":"2026-09-04T21:17:44.649Z","contentChangedAt":"2026-09-04T21:17:44.649Z","schemaVersion":2},"datasetVersion":"2026-09-12T02:17:10.037Z"}