Valgo

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.

9. Treat Or() grouping and OrElse() cut semantics as version-sensitive. Verify both behavior and error shape in matching docs/tests before changing a chain.

10. Keep a one-off validation local. Extract a helper returning *v.Validation when the pattern genuinely repeats. Create a custom validator only for a reusable domain rule that benefits from its own typed API and message key.

11. When the effective Valgo version includes the is subpackage, use its stateless predicates for reusable boolean checks that do not need field paths, messages, localization, or validation-session results. A predicate may be passed to a validator's Passing method when an error is needed.