Skip to content

Productization map: release confidence / shipping readiness

Purpose

This document is a product-boundary audit of the current repository and a concrete map for evolving SDETKit into a globally adoptable product centered on one flagship promise:

Release confidence / shipping readiness for software teams.

This is an inspection and planning artifact. It does not propose broad refactors or functionality removal.

1) Current-state audit

Repository shape (what exists today)

  • Runtime package code sits in src/sdetkit/ with a very broad command surface routed by src/sdetkit/cli.py.
  • The top-level UX is already release-confidence oriented in README.md (gate fast and gate release).
  • Documentation is extensive (docs/), but currently mixes:
  • core user journeys,
  • reference docs,
  • integration guides,
  • a large archive of impact-based reports and completion report pages.
  • scripts/ includes both core workflows (bootstrap.sh, first_proof.py, release_preflight.py) and many impact-specific contract checks.

Package and command surface observations

Stable/public-facing feeling areas

These appear closest to stable product surface:

  • Core release flow:
  • gate, doctor, security, evidence
  • Supporting operational surface:
  • repo, ci, maintenance, policy, report, production-readiness.
  • Practical utility commands with clear contracts:
  • kv, apiget, patch, cassette-get.

Confusing/overlapping/internal-feeling areas

  • Very large set of impact/completion command modules in src/sdetkit/ (including many legacy numeric-series modules and many *_completion modules).
  • CLI has to hide many commands from main help, which is itself a signal that product boundaries are still blurred.
  • Docs navigation includes strong flagship pages plus a very large historical/report corpus in the same visible namespace.
  • Command naming has overlap in places (weekly-review, weekly-review-lane, impact-specific completions), which can feel incubator-like to external adopters.

2) Classification of current contents (public/stable / advanced but supported / experimental/incubator)

Classification is based on current repository contents and naming patterns.

Public / stable

Definition: mandatory, high-confidence paths directly tied to release confidence / shipping readiness.

  • Runtime commands and modules:
  • gate, doctor, security, evidence, production_readiness, repo, ci, policy, report.
  • Wrapper workflows:
  • ci.sh, quality.sh, security.sh.
  • Primary docs:
  • README.md, docs/index.md, docs/release-confidence.md, docs/decision-guide.md, docs/recommended-ci-flow.md, docs/adoption.md, docs/adoption-troubleshooting.md.

Advanced but supported

Definition: ecosystem connectors and platform-specific interoperability that extend the core.

  • CLI/module areas:
  • agent/*, notify, notify_plugins, plugin_system, plugins, github_actions_quickstart, gitlab_ci_quickstart, n8n docs, omnichannel/bridge docs.
  • Packaging extras and entry points indicating external systems:
  • optional dependencies for Telegram and WhatsApp.
  • Example integration assets:
  • examples/ci/*, template-related CI docs/pages.

Experimental

Definition: incubator/history-heavy surfaces that are useful but should not define first-time product identity.

  • Most dayNN_* and *_completion modules in src/sdetkit/.
  • -based contract scripts in scripts/check_day*.py and impact-specific completion checks.
  • Large archive of impact-based docs and integration completion pages in docs/.
  • Long-tail command aliases and hidden command behavior currently needed to keep main help usable.

3) Public/stable vs boundary clarity statement

Treat as public/stable now

  • python -m sdetkit gate fast
  • python -m sdetkit gate release
  • python -m sdetkit doctor
  • sdetkit security ...
  • sdetkit evidence ...
  • sdetkit repo ...
  • sdetkit ci ...

Treat as "advanced but supported"

  • policy, report, maintenance, ops, notify, agent, integration quickstarts.

Treat as incubator/legacy workflow (explicit opt-in)

  • Day, impact and completion command families and their matching report documentation.
  • Campaign-style command names where scope is readiness-specific rather than evergreen.

4) Proposed target taxonomy (for future productization)

Keep implementation mostly where it is for now, but define a target taxonomy to guide future incremental changes.

Runtime package taxonomy (target)

sdetkit/
  core/           # release gate, doctor, security, evidence, readiness contracts
  integrations/   # CI providers, chat/notify adapters, external connectors, plugin adapters
  playbooks/      # guided onboarding, rollout, adoption, governance playbooks
  experimental/   # incubator lanes, day/impact completions, unstable aliases
  cli/            # user-facing command routing (thin), help profiles, command visibility policy

Notes: - This is a target map, not a migration request in this PR. - Existing modules can be progressively wrapped/aliased into this taxonomy over multiple small PRs.

CLI taxonomy (target)

Top-level command groups should converge toward:

This has since shipped as four help groups in sdetkit --help (see CLI reference):

  1. Release confidence: gate, doctor, security, evidence, release, report.
  2. Diagnose and adopt: diagnose, verify, investigate, mission-control, adoption-surface, fit, adoption, init, repo, maintenance and similar.
  3. SDET utilities: kv, apiget, cassette-get, patch, inspect, serve and similar.
  4. Advanced: kits, intelligence, integration, forensics, ops, release-room, review and similar.

5) Proposed docs information architecture (few top-level journeys)

Recommended top-level docs journeys:

  1. Start here (5 minutes)
  2. Quick confidence, release gate, and first pass/fail interpretation.
  3. Adopt in CI/CD
  4. GitHub/GitLab/Jenkins templates, rollout order, troubleshooting.
  5. Operate at scale
  6. Evidence packs, policy, reporting, governance patterns.
  7. Integrations
  8. Notifications, agent/automation bridges, plugin adapters.
  9. Playbooks
  10. Outcome-based guided lanes (onboarding, contribution, reliability narratives, etc.).
  11. Experimental / archive
  12. /impact completion history and incubator commands, clearly marked as non-primary.

Practical IA rule: - Keep only journeys 1-4 prominently in README and docs landing pages. - Link playbooks as guided optional paths. - Keep experimental/archive content accessible but visually de-emphasized.

  1. Boundary declaration PR
  2. Add a concise "stability levels" doc and link it from README + docs index.
  3. CLI discoverability PR
  4. Introduce clearer help grouping that labels commands as Core / Integrations / Playbooks / Experimental.
  5. Docs IA PR
  6. Reorganize MkDocs nav to foreground 3-5 flagship journeys and move day/impact history under archive sections.
  7. Compatibility PR
  8. Add explicit alias/compatibility matrix for legacy impact/completion commands.
  9. Incremental module convergence PRs
  10. Move only a few modules at a time toward target taxonomy with tests and deprecation notes.

7) Key risks and ambiguities

  • Risk: product identity dilution. The breadth of commands and impact-history artifacts can overshadow the flagship release-confidence promise.
  • Risk: accidental breaking change. Aggressive command cleanup could break existing automation that depends on legacy names.
  • Risk: docs overload for first-time users. Too many equally prominent pages slows adoption.
  • Ambiguity: long-term status of impact/completion modules. Need maintainers to decide: archive-only, supported-long-tail, or scheduled deprecation.
  • Ambiguity: naming end-state. Whether to keep flat top-level commands forever or migrate to grouped command namespaces with aliases.

8) Decision checkpoints for maintainers

Before implementation-heavy refactors, explicitly decide:

  1. Which commands are "public/stable" with compatibility guarantees.
  2. Which commands are "supported/advanced" without long-term frozen interfaces.
  3. Which commands are "experimental/incubator" and may change quickly.
  4. Documentation SLA for each tier (full docs vs brief reference vs archive-only).

Those decisions will reduce future refactor risk and let SDETKit scale as a product with a clearer boundary contract.