valgo

name

valgo

description

Add, refactor, debug, review, explain, or migrate type-safe validation in consumer Go applications using github.com/cohesivestack/valgo. Use for new or existing Valgo integrations, validator and rule selection, nested or conditional validation, errors and localization, reusable or custom validators, migrations from tag-based validation libraries, and version-compatible Valgo code generation and verification.

Valgo

Use Valgo in an application that consumes the library. Do not use this skill to develop, maintain, or contribute to Valgo itself. For upstream Valgo work, follow that repository's contributor instructions and treat its source and tests as the implementation under change.

Inspect the consumer project

Start from the project root and inspect before editing:

1. Read repository instructions and locate go.mod, go.work, vendor/, relevant packages, tests, and generated-code policies.

2. Inspect package organization, request or domain types, JSON/form field naming, error handling, HTTP framework conventions, localization needs, and existing validation helpers.

3. Determine whether Valgo is installed and resolve the code actually built:

   go list -m -json github.com/cohesivestack/valgo
   

4. Record Version, Dir, GoMod, and any Replace value. Inspect vendored code or a local replacement when the build uses it; a tag alone is then not the effective API.

5. Preserve the installed version. Do not run an upgrade, change a replacement, or add a second validation library unless the user explicitly requests it.

6. For a new integration, identify the latest stable Valgo release whose go.mod is compatible with the project's Go version:

   go list -m -versions github.com/cohesivestack/valgo
   go list -m -json github.com/cohesivestack/valgo@vX.Y.Z
   

   Add the selected explicit version. Do not hard-code the version listed in this skill.

If go list reports that Valgo is absent, add it only when the requested work requires a new integration or migration.

Resolve API details in source-of-truth order

Use this priority:

1. The API in the effective Valgo source used by the consumer project (Dir, replacement, or vendor tree).
2. Valgo documentation from the same release or minor-version snapshot.
3. This skill's references.
4. Latest Valgo documentation only for a new integration or explicit upgrade.

Never silently use master APIs in a project pinned to an older release. If documentation and source disagree, investigate the version boundary and follow the effective source. Use go doc, source declarations, and package tests to settle ambiguity. Never invent a constructor, rule, session method, option, or error helper. If matching docs are not shipped with the effective source, retrieve them from the exact release tag rather than the latest branch.

Read only the matching documentation needed for the task:

• Setup and sessions: getting-started.md and using-valgo/validation-sessions.md
• Validator selection and rules: validators/overview.md, validators/rule-index.md, and the relevant validator page
• Stateless boolean rules: validators/predicates.md when that page and the github.com/cohesivestack/valgo/is package exist in the effective version
• Nested values and slices: using-valgo/namespaces.md
• Result queries and conditional work: using-valgo/querying-results.md and using-valgo/conditional-flows.md
• Errors, localization, and factories: using-valgo/errors.md and using-valgo/localization.md
• OR behavior: validators/or-operators.md (or the matching older page)
• Extension and reusable patterns: extending/custom-validators.md and the relevant cookbook/ page
• Release differences: migration.md

When versioned docs exist, select the directory matching the installed minor release. Use unversioned latest docs only under priority 4 above.

Load bundled references selectively

• Read references/rule-index.md before choosing an unfamiliar constructor or translating rules from another library. Confirm every selected API against the installed version.
• Read references/patterns.md only for the requested feature: pointers, namespaces, slices, conditionals, errors, localization, factories, reuse, custom validators, Or(), or OrElse().
• Read references/version-notes.md when the project is pinned, replaced, vendored, being upgraded, or uses a deprecated name. Treat it as a risk checklist, not a changelog.

Design the validation

1. Preserve the project's existing field paths, titles, message language, response schema, and boundary between validation and transport handling.

2. Prefer the conventional alias for a new import:

   import v "github.com/cohesivestack/valgo"
   

   Preserve a different established alias.

3. Keep Valgo's function-based model. Do not introduce validation struct tags.

4. Select the narrowest validator compatible with the Go value's exact type. On versions with generalized numeric constructors, use Int/IntP for signed integers, Uint/UintP for unsigned integers, and Float/FloatP for floating-point values regardless of width. On older versions, use the width-specific constructor. Do not replace pointer absence with a sentinel zero value. For strings, use EqualTo for exact equality. Use EqualFold only when the effective version provides it and Unicode simple case-insensitive comparison is intended; it does not normalize text or perform full case folding.

5. Give validators stable machine-readable names. Use titles only when display text must differ from the field name.

6. Use In for nested objects, InRow for slices of objects, and InCell for slices of scalar values. Match the project's dot/index path convention.

7. Keep session operations separate from validator rules:

   • Build or extend sessions with Is, Check, New, In, InRow, InCell, If, When, Do, and Merge only when supported.
   • Chain rules such as Not, Blank, Between, or Passing on a type-compatible validator.

8. Use Is for the usual first-failure-per-validator behavior. Use Check only when the consumer needs every failing message in a chain. Use New for sessions assembled over multiple statements.

Follow the task-specific workflow

Add or change validation

Translate requirements into exact Go value types, field paths, rules, and expected errors. Implement the smallest change that fits existing package and handler conventions. Do not replace project error handling merely because Valgo offers another output form.

Review, debug, or refactor

Trace each input value through its constructor, rule chain, namespace, session operation, and error conversion. Check pointer nil behavior, rune-versus-byte length, OR precedence, conditional evaluation timing, unknown-path queries, and Is versus Check. Preserve observable behavior during refactors unless the user requests a behavior change.

Migrate another validation library

1. Inventory tags, aliases, registered custom rules, cross-field checks, conditional rules, slice traversal, translations, and error response code.
2. Capture existing valid/invalid cases and error paths in tests before replacing behavior.
3. Map each rule explicitly to an installed Valgo API or an ordinary Go/custom predicate. Do not infer a same-named Valgo method from a source-library tag.
4. Convert required according to the Go type and desired whitespace semantics; convert omitempty using pointers or explicit Go conditions; convert slice traversal with InRow or InCell; express cross-field rules with typed Go values and conditional session flow.
5. Preserve JSON/form names and the external error contract. Remove the old dependency only when the requested migration is complete and no usages remain.

Verify the result

1. Format every modified Go file with gofmt.
2. Compile and run the narrowest relevant tests, then run go test ./... when practical.
3. Run project-specific integration or handler tests that assert status codes, error paths, messages, locale, and JSON shape.
4. If dependency metadata changed, inspect go.mod and go.sum; run go mod tidy only when appropriate, and verify it did not upgrade Valgo or unrelated dependencies unexpectedly.
5. Search edited code for guessed or deprecated APIs and compare them with the effective source.
6. Review the final diff for accidental abstractions, unrelated edits, changed error conventions, and version drift. Report commands run and any checks that could not be completed.