testeiya 0.8.1 → 0.10.0

package/skills/codeceptjs/lint-codeceptjs-tests/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: lint-codeceptjs-tests
+description: >
+  Use when a CodeceptJS 4 suite needs a static quality gate — before committing
+  tests, reviewing a PR that touches tests, hardening CI, or on direct asks:
+  "lint the tests", "find I.wait / setTimeout sleeps", "leftover .only or
+  pause()", "missing await on grab", "passwords printed in logs", "why are
+  tests slow/flaky". Runs `@codeceptjs/lint` — an AST-based linter that needs
+  no CodeceptJS install and no browser.
+---
+
+# Lint CodeceptJS 4 Tests
+
+`@codeceptjs/lint` reads tests, page objects and helpers as an AST and reports the smells that make suites slow, flaky or leaky — fixed sleeps, `if` branching, raw `fetch`, missing `await` on grabbers, plain-text credentials, leftover `.only`/`pause()`. One finding per line; exit codes `0` / `1` (errors found) / `2` (bad input, unparsable file) drop straight into CI.
+
+## Commands
+
+```bash
+npx @codeceptjs/lint                          # files from codecept.conf.js in cwd
+npx @codeceptjs/lint tests/ pages/login.js    # explicit paths (no config needed)
+npx @codeceptjs/lint -r no-pause -r no-only   # only these rules (or --rules a,b)
+npx @codeceptjs/lint rules                    # list rules + defaults
+npx @codeceptjs/lint --json                   # file, line, column, rule, level, message, source
+npx @codeceptjs/lint -c e2e/codecept.conf.js  # config in another directory
+```
+
+Without paths it reads `codecept.conf.js|ts|cjs|mjs` and lints everything matched by `tests`, local `include` files (page objects, steps file) and helpers loaded via `require`. TypeScript is parsed with Node's type stripping (Node 22.13+); `enum`/`namespace` report as parse errors. A TS config importing `./x.js` for an `x.ts` file (tsx convention) loads when the project has `tsx` installed.
+
+## Rules and the fix for each
+
+| Rule | Default | Detects → fix |
+|---|---|---|
+| `no-fixed-wait` | error | `I.wait(5)` → `I.waitForElement` / `I.waitForText` / `I.see` |
+| `no-sleep` | error | bare and `window.`/`globalThis.` `setTimeout`, incl. `await new Promise(r => setTimeout(r, ms))` and `timers/promises`, outside helpers → condition wait |
+| `no-if-in-test` | error | `if` inside a Scenario/hook → `tryTo()` from `codeceptjs/effects` |
+| `no-fetch` | error | `fetch()` (incl. `window.fetch`, `globalThis.fetch`) outside helpers → REST helper `I.sendGetRequest` / `I.sendPostRequest` |
+| `no-console` | warn | `console.*` outside helpers → `I.say()` (lands in the report) |
+| `no-only` | error on CI, warn locally | `Scenario.only`, `Feature.only`, `Data(...).only` → remove before commit |
+| `no-pause` | error on CI, warn locally | `pause()`, `this.pause()` → remove before commit |
+| `no-skip` | warn | `Scenario.skip`, `Feature.skip`, `xScenario`, `xFeature` → intentional? suppress with a comment explaining why |
+| `secret-credentials` | error | credential-ish `process.env.X` / `process.env['X']` or a password/token/secret/api-key locator passed to `I.*` → wrap with `secret()` |
+| `await-grab` | error | `I.grab*()` assigned, destructured or passed without `await` (`await Promise.all([...])` and `.then()` chains are fine) → add `await` |
+| `no-actor-in-helper` | error | `I` inside a class extending `Helper` → `this.helpers['Name']` |
+| `raw-browser-in-test` | warn | `I.use*To`, `I.executeScript` in a Scenario → move into a helper or page object |
+
+"On CI" = the `CI` env var is set — local debugging stubs (`pause()`, `.only`) stay warnings so they don't fail the lint while investigating.
+
+## Configuring per project
+
+Levels live in the config, next to the tests they govern:
+
+```js
+export const config = {
+  tests: './*_test.js',
+  lint: {
+    rules: { 'no-if-in-test': 'warn', 'raw-browser-in-test': 'off' },
+  },
+}
+```
+
+Levels: `error`, `warn`, `off`. For a single deliberate case, suppress inline — rule id required, never disable a rule project-wide for one line:
+
+```js
+I.wait(1) // codeceptjs-lint-disable-line no-fixed-wait
+```
+
+## Workflow
+
+1. Run `npx @codeceptjs/lint` at the project root; if no config loads (secrets, tsx-less TS config), pass paths explicitly.
+2. Fix errors first (they fail CI), warnings by judgment. Triage by cost: sleeps and missing `await` are the flakiness drivers; `secret()` fixes are one-line.
+3. For bulk cleanup, feed `--json` output to drive file-by-file edits — the `source` field holds the offending line (truncated to 120 chars).
+4. Add the gate so it stays clean:
+
+```yaml
+# CI, before codeceptjs run
+- run: npx @codeceptjs/lint
+```
+
+For agent-driven work, a Claude Code `PreToolUse` hook blocks edits that *add* a new error (pre-existing errors and warnings never block; a failing hook allows the edit):
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      { "matcher": "Write|Edit|MultiEdit", "hooks": [{ "type": "command", "command": "npx @codeceptjs/lint --hook claude" }] }
+    ]
+  }
+}
+```
+
+## Things to avoid
+
+- "Fixing" `await-grab` by deleting the `await` usage — the grab result is a promise, the fix is `await`, not removal.
+- Replacing `I.wait` with a longer `I.wait`.
+- Suppressing `no-if-in-test` when the branch is load-bearing — that's `tryTo()` or a helper's job.
+- Adding the CI step before triaging existing findings — the suite goes red on day one.
+- Skipping the hook's config scope check — it only lints files the config covers.
+
+## Related skills
+
+- `debugging-codeceptjs-tests` — `I.wait(N)` as a timing probe is fine mid-debug, lint-clean it before committing
+- `refactoring-codeceptjs-tests` — bulk cleanup of a lint-red suite (extract helpers, tame locators)
+- `writing-codeceptjs-tests` — write clean tests from the start
+- `ci-fix-tests` — run the lint gate first so CI fixes don't reintroduce smells

package/skills/skills.lock.json

@@ -3,12 +3,14 @@
     {
       "source": "testomatio/skills",
       "ref": null,
-      "sha": "050ece13c42d3bc0f0020336aabebe21fe62cb41",
+      "sha": "e1cf03227adfcb553c94ea5ee08c0eebc397e875",
       "folder": "testomatio",
       "skills": [
         "automate-manual-test-cases",
+        "catalog-features",
         "debug-fix-failed-flaky-autotests",
         "detect-duplicate-test-cases",
+        "detect-product-mismatches",
         "detect-useless-tests",
         "epic-requirements-specification",
         "explorbot-fundamentals",
@@ -46,7 +48,7 @@
     {
       "source": "codeceptjs/skills",
       "ref": null,
-      "sha": "d3d6a4e0e29207b1afb051eeb6f5f36984f4752b",
+      "sha": "c9a82e3e237c908ba53ec47d2c841c680b88e03a",
       "folder": "codeceptjs",
       "skills": [
         "ci-fix-tests",
@@ -55,6 +57,7 @@
         "codeceptjs-fundamentals",
         "codeceptjs-run-analysis",
         "debugging-codeceptjs-tests",
+        "lint-codeceptjs-tests",
         "migrate-codeceptjs-4",
         "migrate-cypress-to-codeceptjs",
         "migrate-protractor-to-codeceptjs",

package/skills/testomatio/qa-process/testing-workflow/SKILL.md

@@ -17,7 +17,9 @@ Orchestrates the test case lifecycle by routing requests to specialized skills a
 | `qa-thinking`                        | Analyze a feature as QA — edge cases, negative flows, abuses, risk scenarios      |
 | `qa-split-testing-levels-pyramid`    | Apply the test pyramid — assign scenarios to testing levels, coverage split       |
 | `write-user-story`                    | Write user stories and acceptance criteria (the requirements)                     |
-| `wiki-from-code`                      | Build or refresh a product wiki from implemented code (implicit requirements)     |
+| `wiki-from-code`                     | Build a whole-product wiki from code, or update it after large changes            |
+| `catalog-features`                   | Catalog features of one source: code, issue tracker, requirements, user docs      |
+| `detect-product-mismatches`          | Compare code, issues, requirements, user docs with each other — mismatches        |
 | `qa-requirement-reviewer`            | Review requirements for ambiguity, gaps, and testability                          |
 | `qa-write-test-cases`                | Generate new test cases and checklists from requirements                          |
 | `improve-test-cases`                 | Improve existing test cases quality                                               |
@@ -38,7 +40,9 @@ Orchestrates the test case lifecycle by routing requests to specialized skills a
 - Flows are examples, not exhaustive. Combine or extend them when a request spans several tasks.
 - When suggesting next steps, take into account the flows, context, user request, and results of previous steps.
 - **Write / draft user stories** (requirements, spec, acceptance criteria) → route to the `write-user-story` skill. Review of existing requirements → `qa-requirement-reviewer`.
-- **Wiki / spec from code** (build or refresh wiki, implicit requirements, as-implemented docs) → route to the `wiki-from-code` skill.
+- **Wiki / spec from code** (build or update the whole-product wiki, actual behavior, implicit requirements) → route to the `wiki-from-code` skill.
+- **Catalog features of a source** (codebase, Jira, Confluence, Notion, user docs, etc.; import or sync into the wiki) → route to the `catalog-features` skill.
+- **Compare sources** (code, issues, requirements, user docs: not implemented, differs, unspecified, undocumented) → route to the `detect-product-mismatches` skill.
 - **Behavior questions** ("what happens when…", "can a user…", "is X supported") ask what the product does rather than for an artifact → route to the `qa-explain-behavior` skill first, then continue with the flow the answer points to.
 - **Strategic intent** ("where do I start", "improve our QA process", "QA maturity review") → route to the `qa-lead-strategy-advisor` skill instead. It owns the high-level roadmap and delegates execution back here.
 
@@ -47,14 +51,15 @@ Orchestrates the test case lifecycle by routing requests to specialized skills a
 ### Wiki from Code Flow
 
 ```
-User: asks to build/refresh a wiki, requirements, or spec from the codebase
+User: asks to build/update a wiki, requirements, or spec from the codebase
 =>
-Use `wiki-from-code` skill to bootstrap or refresh `wiki/` from implemented code
+Use `wiki-from-code` skill to build or update `wiki/` from implemented code
 =>
 After the wiki is written, suggest next actions:
-1. 🧠 Risk scenarios from a capability (with `qa-thinking` skill)
-2. 📝 Test cases from a capability (with `qa-write-test-cases` skill)
-3. 📘 User stories from a capability (with `write-user-story` skill)
+1. 🔍 Cross-check with issues, requirements, user docs (with `detect-product-mismatches` skill)
+2. 🧠 Risk scenarios from a feature (with `qa-thinking` skill)
+3. 📝 Test cases from a feature (with `qa-write-test-cases` skill)
+4. 📘 User stories from a feature (with `write-user-story` skill)
 ```
 
 ### Test Generation Flow

package/skills/testomatio/requirements/catalog-features/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: catalog-features
+description: >-
+  Builds a catalog of product features from one source: a tree that mirrors the source, each feature as a key, title, and link to the source. Code, issues, requirements, docs, etc. are supported.
+  Use when asked to catalog/list features, existing functionality, issues, requirements, specs, PRDs, user docs or similar sources.
+metadata:
+  author: Testomat.io
+  version: 1.0.0
+---
+
+# Catalog features
+
+Catalog of **the source's features**: a tree that mirrors the source, each feature with its key, title, and link. Its behaviors (description, requirements, acceptance criteria, etc.) stay at the source.
+
+Output folder: given by the calling skill or the user. Default: `features/.catalog/`. Write only inside it.
+
+## Modes
+
+`build` from scratch; `update` from an existing catalog. When `update`, use info from the catalog README.
+
+## Source roles
+
+| Role       | Description                                                 |
+| ---------- | ----------------------------------------------------------- |
+| Actual     | Actual behavior of the product. Code, configs, etc.         |
+| Intended   | What we attempted to implement. Requirements, tickets, etc. |
+| Documented | What the product says it does. User docs, etc.              |
+
+## Rules
+
+- **Read-only on the source.** Do NOT edit the source even when the tools offer it.
+- One catalog per source.
+
+## Sources
+
+### Code
+
+- Tree: areas → features, named from what the product does for its users, not from the stack or code folders, classes, files, or functions.
+- Feature: one per feature, not per file; same feature in two places → one feature. Link: repo paths of the main implementation (route, screen, job), not every file.
+- Scope: features users can reach now. Not stubs, routes users cannot reach, or features behind disabled flags; comments, docs, and tests do not make a feature.
+- `update`: `git diff --name-status -M {baseline}..HEAD`; take into account renamed, moved, deleted files.
+- Role: Actual.
+- History: No.
+
+### Issue tracker
+
+- Tree: the tracker's hierarchy: initiatives, epics, parent issues, issues, sub-tasks, etc.
+- Scope: a query (JQL, `gh` search, Linear filter, etc.); ask the user for it and store it. "Done" issues only (typical successfully resolved statuses); ask the user when in doubt.
+- Role: Intended.
+- History: Yes (unless user specified). Because different issues may be related to the same feature. Need to store date of creation and resolution to determine which issue overrides the other.
+
+### Requirements
+
+- Word, PDF: extract the text first.
+- Tree: area by heading or other logical structure.
+- Scope: ask user for the scope and other crucial filters. Take into account that there could be drafts, deprecated pages, copies. Process them accordingly.
+- Role: Intended.
+- History: No.
+
+### User docs
+
+- Tree: keep the original structure with required hierarchy levels.
+- Role: Documented.
+- Scope: ask user.
+- History: No.
+
+### Other
+
+Any source that describes the product. Agree on role, coverage, history with the user before syncing. 
+
+## Steps
+
+```
+- [ ] 1. Source and domain
+- [ ] 2. Inventory
+- [ ] 3. Write the tree
+- [ ] 4. Validate
+- [ ] 5. Report
+```
+
+Read [references/layout.md](references/layout.md) before writing files.
+
+## 1. Source and domain
+
+Ask the user in one message, unless given:
+
+- Type and access: repository, MCP, CLI, URL, export, or file path. No access → stop and ask for an MCP connection or an export.
+- Scope as a concrete, repeatable filter: repo paths, tracker query (JQL, project, label), root page or space, docs root.
+- Domain: what the product does and for whom, key terms. Not given → infer it from the source.
+
+Name area and features in the domain terms.
+
+Several sources in one run → one output folder each; define all of them first, then run steps 2–4 per source.
+
+## 2. Inventory
+
+List every feature in scope with key or URL, title, status. Navigate all the pages.
+
+When `update`: take into account renamed, moved, deleted files. Process them accordingly.
+
+If source is code create areas and features based on features and logic, not just files, classes, functions.
+
+## 3. Write the tree
+
+Catalog README and area READMEs, as [references/layout.md](references/layout.md) describes.
+
+## 4. Validate
+
+```markdown
+Structure
+- [ ] Catalog README has every fact and the counts; indexes every area
+- [ ] Every area README lists its subareas and features; the tree mirrors the source
+
+Content
+- [ ] Every feature yml is according to the `references/layout.md`
+- [ ] Code: areas and features named from the product, not the stack
+- [ ] Update: features gone from scope removed
+- [ ] Only existing keys and urls are used in the catalog
+```
+
+## 5. Report
+
+Where to start. Features synced, skipped by reason.
+
+To a calling skill: features added, changed, and removed.
+
+## Next actions
+
+- `detect-product-mismatches`
+- Feature pages from the code → `wiki-from-code`
+- `qa-requirement-reviewer`
+- Test cases from requirements → `qa-write-test-cases`

package/skills/testomatio/requirements/catalog-features/references/layout.md

@@ -0,0 +1,43 @@
+# Catalog layout
+
+The tree mirrors how the source groups its content: code areas, epics, page tree, docs nav.
+
+```
+features/.catalog/           # output folder
+  README.md                  # source facts, counts, areas, ungrouped features
+  {area}/                    # code area, epic, parent page, nav section; any depth
+    README.md                # the area's own link/path, subarea if any, its features
+    {feature}.yaml           # feature page
+    {subarea}/               # subarea (optional)
+      README.md              # the subarea own link/path, name, its features; breadcrumbs
+      {feature}.yaml         # feature page; breadcrumbs; feature info (below)
+    ...
+```
+
+## Formatting
+
+Every `.md` should include info about its entity and child entities list (if any). Relative links between catalog pages.
+
+README.md in catalog root:
+
+| Fact    | Value                                                                                                 |
+| ------- | ----------------------------------------------------------------------------------------------------- |
+| Type    | Code, issue tracker, requirements, user docs or any other                                             |
+| Role    | Actual, Intended, or Documented (SKILL.md › Source roles)                                             |
+| Scope   | Defined by user (or inferred)                                                                         |
+| History | Important for sources like issue tracker                                                              |
+| Access  | MCP, CLI, URL, files                                                                                  |
+| Date    | Date of this sync; code: baseline commit and its date; issue tracker: date of creation and resolution |
+| Domain  | What the product does and for whom; infer if not given                                                |
+
+## Feature YAML
+
+Name: {feature-name}.yaml
+
+Feature YAML should include:
+
+- Key [optional]. Do not invent. Use only if the source provides it.
+- Title: short description of the feature.
+- Links/headings: link(s) to sources that describe the feature (url, repo path, etc.); headings in case source is a document.
+
+No description, requirements or other details.

package/skills/testomatio/requirements/detect-product-mismatches/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: detect-product-mismatches
+description: >-
+  Compares what different sources say the product does: code (actual behavior), issue tracker and requirements (intended behavior), user docs (documented behavior), and any other source (test cases, release notes etc.).
+  Checks every feature in every source and records mismatches: contradictions and differences, not implemented, unspecified, undocumented.
+  Use when the user asks to compare, cross-check, align, validate requirements, specs, wiki, tickets, issues, user docs, or code, codebase against each other, to find mismatches, contradictions, differences, or outdated docs or requirements, or to find what is not implemented, not documented, or not specified.
+metadata:
+  author: Testomat.io
+  version: 1.0.0
+---
+
+# Detect product mismatches
+
+Checks each feature in every source and records where the sources disagree.
+
+Output folder:
+  - given by calling skill or the user
+  - all paths are relative inside the output folder
+  - default: `mismatches/`
+
+> `wiki/mismatches/` is the output of `wiki-from-code`: mismatches inside a single source, the code. Don't use it as the output folder and don't use its results.
+
+## Modes
+
+`build` (from scratch) or `update` (for changes since the last check).
+
+## Sources
+
+Type, role, scope, and history of each source come from its catalog README (`catalog-features` › Source roles, Sources).
+
+| Source        | Role                  |
+| ------------- | --------------------- |
+| Code          | Actual                |
+| Requirements  | Intended              |
+| Issue tracker | Intended              |
+| User docs     | Documented            |
+| Other         | As its catalog README |
+
+Per feature, what each source says is rewritten as behaviors in one shape ([features.md](references/features.md) › Behaviors), so sources compare line by line:
+
+- Two sources say different things about the same behavior → Differs.
+- Another source has a behavior the code lacks → Not implemented. Code is the product: it must do what the other sources say.
+- Several intended sources: a feature is specified when any of them has it.
+- `History: Yes` (issue tracker by default): the newest issue wins (resolution date, else creation date); older contradicting issues are superseded, not mismatches.
+
+**Not a mismatch:**
+
+- Same behavior in other words.
+- **Silence on a detail.** A coarser source agrees with a finer one unless it contradicts it (`Customer can save a card.` agrees with `Customer can save up to 5 cards.`).
+- A behavior only the code has, inside a feature the other sources have.
+- Superseded issues; behaviors of another version; content outside a catalog Scope (open issues, drafts, deprecated pages).
+- Can't tell (vague behavior, unreadable content) → open question.
+
+## Likely cause
+
+From dates read at the source: issue resolution date (else creation date), page last version, docs "last updated" (else `git log -1 --format=%cs -- {path}`); code: `git log -1 --format=%cs -- {paths}` for the feature's code paths. The same dates decide the newest issue for `History: Yes`.
+
+- Code differs from the newest intended behavior, and nothing newer explains it → Bug.
+- Requirement older than the issue or code change that set the current behavior → Stale requirement.
+- User docs older than that change → Stale docs.
+- Otherwise → Decide (product owner).
+
+## Steps
+
+```
+- [ ] 1. Sources and access
+- [ ] 2. Catalogs: create missing, update stale
+- [ ] 3. Check each feature (one subagent each)
+- [ ] 4. Verify (subagents)
+- [ ] 5. Merge
+- [ ] 6. Validate
+- [ ] 7. Report
+```
+
+Read [references/features.md](references/features.md) and [references/layout.md](references/layout.md) before writing files.
+
+## Rules
+
+- **Read-only on sources.** Never edit issues, pages, or code.
+- Catalogs and `features/` change only by running their skills.
+- **Report, don't decide.** A mismatch page shows what each source says; its Solution only suggests a fix.
+- Compare behaviors, not wording: different values, conditions, roles, labels, or flows differ.
+- Write only paths, keys, and URLs that exist in the catalogs, the sources, or the repo. Do not invent them.
+
+## 1. Sources and access
+
+1. List the sources to compare: given by the user, else ask; offer the ones already cataloged.
+2. Check access: one real read per source (MCP tool, `gh`, git, URL, file). No access → stop and ask for an MCP connection or an export. A catalog alone is not enough: behaviors are read at the source.
+
+## 2. Catalogs
+
+Every listed source needs a catalog. Create the missing ones, update the stale ones, before any check:
+
+Use `catalog-features` skill to build the catalogs for each source. Use `wiki-from-code` also if **code is the source**.
+
+## 3. Check each feature
+
+Features: every feature from catalogs in this order: code, requirements, user docs, issue tracker, other.
+
+One subagent per feature, in parallel. Each gets: the feature (its feature YAML), the compared sources (name, type, role, scope, history, access, catalog path), the version, the Domain from the catalog READMEs, the source table and rules above, [references/features.md](references/features.md), [references/layout.md](references/layout.md).
+
+Subagent:
+
+1. Per source: finds the feature in the catalog, else searches the source ([features.md](references/features.md) › Find).
+2. Reads every matching feature at its links and states its behaviors ([features.md](references/features.md) › Read, Behaviors).
+3. Aligns the same behavior across sources.
+4. Returns one mismatch per disagreement: its kind (Differs or Not implemented) and every section of a mismatch page ([layout.md](references/layout.md) › Page), with code evidence as `path:lines`.
+
+Subagent writes nothing. Returns: matched catalog features per source (or `not found` + where searched), mismatches, sources silent on the whole feature, open questions, catalog errors.
+
+## 4. Verify
+
+One fresh subagent per batch of mismatches, with the same inputs as step 3. It re-reads each mismatch at its Links and returns it as confirmed, corrected, or dropped (with why). Can't confirm → open question.
+
+## 5. Merge
+
+1. Write the confirmed mismatch pages ([layout.md](references/layout.md) › Page). Same disagreement from several features → one mismatch page, every disagreeing source on it.
+2. `update`: remove resolved mismatches.
+3. In `mismatches/README.md`, write the mismatches list ([layout.md](references/layout.md) › README).
+4. New `sources/` or `mismatches/` → add a link and purpose for it to the root `README.md`.
+
+## 6. Validate
+
+```markdown
+Structure
+- [ ] Every feature of the compared catalogs was checked, or listed as an open question
+- [ ] Mismatches list states compared sources (catalog Date or baseline), version, check date; indexes every page and missing feature
+
+Content
+- [ ] Each page has every section of [layout.md](references/layout.md) › Page and one row per compared source; silent sources marked silent with where searched
+- [ ] Difference opens with a one-sentence summary; each bullet is clear alone: sources, condition, what the user gets; the title doesn't say which side is right
+- [ ] Every page was confirmed in Verify; nothing from Not a mismatch is a page
+- [ ] Every behavior on the pages passes the check in [references/features.md](references/features.md)
+- [ ] update: resolved pages removed
+```
+
+## 7. Report
+
+Where to start. Mismatches by highest user impact first. Missing features per source. Catalog errors (→ `catalog-features`; code catalog with `features/` → `wiki-from-code`). Open questions.
+
+## Next actions
+
+- Update a catalog → `catalog-features`; feature pages from code → `wiki-from-code`
+- User stories for not-implemented behavior → `write-user-story`
+- Review contradicting requirements → `qa-requirement-reviewer`
+- Test cases for differing behavior → `qa-write-test-cases`

package/skills/testomatio/requirements/detect-product-mismatches/references/features.md

@@ -0,0 +1,84 @@
+# Features
+
+A feature is something the product does for its users that they would name: "Pay with saved card", "Export report to CSV". In a catalog, one feature YAML is one feature of its source, in the area where the source puts it. Another source may name it differently or split it differently: e.g. one epic covers three code features, one docs page covers two.
+
+A feature is made of behaviors: what someone who uses it (end user, admin, API client, integrated system) can do, see, or get, and when. Sources are compared behavior by behavior, so every source's behaviors are written the same way.
+
+Behavior is similar to requirement or acceptance criteria, but those terms describe intended behavior; code gives actual behavior, user docs documented behavior (`catalog-features` › Source roles). "Behavior" fits every role: implemented, planned, or documented.
+
+## Find
+
+Per source:
+
+1. Catalog: key, title, the area it sits in. Links in the feature YAML to other sources help.
+2. Not in the catalog → search the source, within the catalog's Scope:
+
+| Source        | Search                                                                                 |
+| ------------- | -------------------------------------------------------------------------------------- |
+| Code          | Domain terms, UI labels, messages, routes; start next to related features' code        |
+| Issue tracker | Text search inside the catalog's Scope query (JQL `text ~ "term"`, `gh search issues`) |
+| Requirements  | Search under the root page or space (CQL `text ~ "term"`); headings of long documents  |
+| User docs     | Docs site search or nav; `grep` in the docs repo                                       |
+| Other         | The source's own search                                                                |
+
+- Found at the source, missing from the catalog → use it and report a catalog error.
+- Found, but outside the catalog's Scope (open issue, draft, deprecated page or copy, other version) → not a behavior. Mention it on the mismatch page when it explains one.
+- Not found → the source is silent on the feature. Record where you searched.
+
+## Read
+
+Read every matching feature at its links (documents: under its headings). Behaviors come from:
+
+| Source        | Behaviors from                                                                                                                                              | Not behaviors                                                                                                                                     |
+| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Code          | The code at the feature's `code` paths (else its links); Behaviors on its feature page in `features/`, when present, as a start                             | Claims (comments, docstrings, developer docs, API specs, configs, tests); stubs, routes users cannot reach; internal steps with no visible effect |
+| Issue tracker | Stories and feature issues: acceptance criteria, then the description. Epics: their scope. Bugs: the expected result                                        | A bug's reported actual result; tasks, spikes, chores, tech debt                                                                                  |
+| Requirements  | Functional requirements, business rules, acceptance criteria, flows; one behavior per table row and per meaningful matrix cell; exclusions as negative ones | Future phases, nice-to-have, MoSCoW Could and Won't; goals, rationale, personas, metrics, open questions                                          |
+| User docs     | Guides, how-tos, limits, notes and warnings; badges (plan, edition, role, platform) as conditions; navigation steps                                         | Screenshots and videos                                                                                                                            |
+| Test cases    | Expected results                                                                                                                                            | Steps, test data                                                                                                                                  |
+
+- Code behind a flag or setting that can be turned on → a behavior with that condition (as `wiki-from-code`).
+- Comments and later edits may change the body ("dropped", "moved to PROJ-456", "decided: 3 retries, not 5"): state the final behavior, never the comment.
+- Acceptance criteria may sit in a custom field, a description heading, a checklist, or sub-tasks: find the convention in the first issues.
+
+## Behaviors
+
+### Shape
+
+- One behavior per line, one sentence, present tense.
+- No `should`, `shall`, `must`, `will`: state it as a fact. The source's role says whether it is actual, intended, or documented.
+- Name who acts or what changes, in domain terms. Never "the system", "it", or "we".
+- Outcome is what the actor can observe (screen, response, file, email, notification), not how the product gets there.
+- Conditions stay in the behavior: role, platform, setting, state.
+- Source key, when the behavior has one, goes first.
+- Negative behaviors count: `Viewer cannot delete a project.`
+- Split on "and" when each part can be checked on its own.
+
+### Values and words
+
+- Values as the source states them, with units. No value in the source → none in the behavior. Never round, convert, or fill one in; a vague behavior stays vague (open question).
+- Code: exact values from the code that runs; a value read from config or environment: its default, marked `(configurable)` (as `wiki-from-code`).
+- UI labels and messages verbatim, in quotes; navigation paths with `›`.
+- Domain terms (prefer the user docs' terms), one per concept across sources and `features/`.
+- No class, function, table, file, flag, or library names. Protocol details (endpoints, status codes, fields) only when the API is what users use.
+- Keep the source's level of detail: a coarse behavior stays coarse. Never merge behaviors and drop values or conditions.
+- Restate, never paste. Never people, comments, or customer data.
+
+## Examples
+
+| Source says                                                           | Behavior                                                            |
+| --------------------------------------------------------------------- | ------------------------------------------------------------------- |
+| The system shall allow users to store payment methods (max 5).        | `Customer can save up to 5 cards.`                                  |
+| Users can save cards to pay faster.                                   | `Customer can save a card.` (benefit dropped)                       |
+| AC: if the card is declined, show "Payment failed. Try another card." | `Declined card: Customer sees "Payment failed. Try another card."`  |
+| Enterprise customers get SSO; Pro is coming soon.                     | `Enterprise plan: SSO sign-in is available.` (Pro: future, dropped) |
+| Session times out after a while.                                      | `Session expires after inactivity.` (no value invented)             |
+| Bug: saving the same card twice creates a duplicate; expected: one.   | `Saving the same card again keeps one saved card.`                  |
+
+## Check
+
+- [ ] Every source either has the feature or records where it was searched
+- [ ] One observable behavior per line, present tense, who or what named
+- [ ] Values, labels, and conditions exactly as in the source; none added
+- [ ] Domain terms, the same term for the same thing
+- [ ] No implementation, plans, rationale, work items, people, or copied text