143 lines
4.6 KiB
Markdown
143 lines
4.6 KiB
Markdown
|
---
|
||
|
|
name: rename-collections-vocabulary
|
||
|
|
classification: feature
|
||
|
|
success_metric: |
|
||
|
|
UI copy reads "My Collection" (ownership) and "Lists" / "Binders" (curated
|
||
|
|
lists); no rendered string "Owned Cards" / "Mark Owned" / "All My Cards"
|
||
|
|
remains in pages/ or components/; schema unchanged; AGENTS.md extended
|
||
|
|
with vocabulary table.
|
||
|
|
skip:
|
||
|
|
- arch
|
||
|
|
status: open
|
||
|
|
created: 2026-05-27
|
||
|
|
---
|
||
|
|
|
||
|
|
# Convoy: rename-collections-vocabulary
|
||
|
|
|
||
|
|
Align user-facing copy with the product taxonomy: owned cards vs curated lists.
|
||
|
|
|
||
|
|
## Why
|
||
|
|
|
||
|
|
The scanner audit and IA review found inconsistent vocabulary: "Owned Cards",
|
||
|
|
"Mark Owned", and "All My Cards" imply a different mental model than the
|
||
|
|
schema (global `cards` catalog vs per-user ownership via `user_cards` vs
|
||
|
|
curated `collections`). Users confuse "my collection" (everything I own) with
|
||
|
|
"lists/binders" (curated subsets). This convoy is copy + docs only — no
|
||
|
|
schema migration.
|
||
|
|
|
||
|
|
## Scope
|
||
|
|
|
||
|
|
### In scope
|
||
|
|
|
||
|
|
- **Brief 1 — UI copy sweep** (~20 files in `pages/` + `components/`):
|
||
|
|
- Replace stale strings per vocabulary table (IA architect supplies full
|
||
|
|
inventory).
|
||
|
|
- Target removals: `"Owned Cards"`, `"Mark Owned"`, `"All My Cards"`.
|
||
|
|
- Canonical replacements: **"My Collection"** (ownership), **"Lists"** /
|
||
|
|
**"Binders"** (curated lists).
|
||
|
|
- **Brief 2 — docs + rules**
|
||
|
|
- `AGENTS.md` § Branding — vocabulary table.
|
||
|
|
- `.cursor/rules/ui-and-theming.mdc` — copy conventions.
|
||
|
|
- `docs/SCHEMA_MAP.md` — clarify naming vs UI labels (no DDL change).
|
||
|
|
- **`.github/workflows/ci.yml`** — new `forbidden-stale-strings` grep gate
|
||
|
|
(~30s): fail if `"Mark Owned"`, `"Owned Cards"`, or `"All My Cards"`
|
||
|
|
appear in `pages/` or `components/`.
|
||
|
|
|
||
|
|
### Out of scope
|
||
|
|
|
||
|
|
- **Schema renames** — table/column names stay; UI copy only.
|
||
|
|
- **URL slug changes** — `/collections` path unchanged in v1.
|
||
|
|
- **Architecture decisions** — `skip: arch`; IA + UX run explicitly.
|
||
|
|
|
||
|
|
## Roles invoked
|
||
|
|
|
||
|
|
1. `role-ia-architect` — vocabulary table + file inventory (**primary owner**).
|
||
|
|
2. `role-ux-reviewer` — scan flow + nav label consistency.
|
||
|
|
3. `role-implementer` — 2 briefs (serial: Brief 2 after Brief 1).
|
||
|
|
4. `role-reviewer` + `role-design-system-auditor` + `role-a11y-auditor` —
|
||
|
|
copy changes affect screen reader strings.
|
||
|
|
|
||
|
|
Note: **`role-architect` skipped** per `skip: arch`. IA architect owns
|
||
|
|
taxonomy; implementer briefs written by IA + conductor handoff or parent
|
||
|
|
agent.
|
||
|
|
|
||
|
|
## Todos
|
||
|
|
|
||
|
|
- [ ] IA: publish vocabulary table + grep inventory of stale strings
|
||
|
|
- [ ] UX: review scanner + nav + collection views for consistency
|
||
|
|
- [ ] Brief 1 — pages/ + components/ copy sweep
|
||
|
|
- [ ] Brief 2 — AGENTS.md + rules + SCHEMA_MAP glossary
|
||
|
|
- [ ] Add `forbidden-stale-strings` CI job
|
||
|
|
|
||
|
|
## Operator action required
|
||
|
|
|
||
|
|
**None.**
|
||
|
|
|
||
|
|
## Multitask dispatch
|
||
|
|
|
||
|
|
### Slice dependencies
|
||
|
|
|
||
|
|
```yaml
|
||
|
|
slice_dependencies:
|
||
|
|
- brief: 1
|
||
|
|
depends_on: []
|
||
|
|
files:
|
||
|
|
- pages/**/*.js
|
||
|
|
- components/*.js
|
||
|
|
notes: exclude pages/api/**
|
||
|
|
- brief: 2
|
||
|
|
depends_on: [1]
|
||
|
|
files:
|
||
|
|
- AGENTS.md
|
||
|
|
- .cursor/rules/ui-and-theming.mdc
|
||
|
|
- docs/SCHEMA_MAP.md
|
||
|
|
- .github/workflows/ci.yml
|
||
|
|
```
|
||
|
|
|
||
|
|
Serial: Brief 2 after Brief 1 (docs reference final copy).
|
||
|
|
|
||
|
|
**Cross-convoy:** parallel with #1+#2 after `secure-scanner-gemini-key`
|
||
|
|
merges — `/multitask role-implementer` **#5 Brief 1 + #6 + #2 Brief 1**
|
||
|
|
(disjoint files).
|
||
|
|
|
||
|
|
Post-PR audit:
|
||
|
|
|
||
|
|
```
|
||
|
|
/multitask role-reviewer + role-design-system-auditor + role-a11y-auditor
|
||
|
|
```
|
||
|
|
|
||
|
|
Group id: `audit-rename-collections-vocabulary-<pr>`.
|
||
|
|
|
||
|
|
## CI impact
|
||
|
|
|
||
|
|
| Workflow / job | Behavior |
|
||
|
|
| --- | --- |
|
||
|
|
| `forbidden-stale-strings` | **New blocking job** — grep `pages/` + `components/`. |
|
||
|
|
| `visual-diff.yml` | **Likely fires** — widespread UI string changes in pages/components. |
|
||
|
|
| `preview-smoke.yml` | Fires; sign-in CTA wording must stay smoke-compatible. |
|
||
|
|
|
||
|
|
**Smoke caveat:** smoke test 2 asserts `/sign in/i` on login page — do not
|
||
|
|
rename that CTA in this convoy.
|
||
|
|
|
||
|
|
## Decisions to ratify (IA architect)
|
||
|
|
|
||
|
|
1. **"Lists" vs "Binders"** — when to use each term in nav vs empty states.
|
||
|
|
2. **Scanner button label** — replacement for "Mark Owned" (e.g. "Add to
|
||
|
|
session" vs "Confirm card").
|
||
|
|
3. **Admin UI** — out of copy sweep or separate pass?
|
||
|
|
|
||
|
|
## Acceptance criteria
|
||
|
|
|
||
|
|
1. Zero rendered occurrences of the three forbidden strings in `pages/` +
|
||
|
|
`components/`.
|
||
|
|
2. Vocabulary table committed in `AGENTS.md`.
|
||
|
|
3. `forbidden-stale-strings` CI green.
|
||
|
|
4. Schema DDL unchanged (grep `migrations/` — no new files).
|
||
|
|
5. Vitest 21/21; smoke 3/3 (sign-in CTA intact).
|
||
|
|
|
||
|
|
## Out of scope follow-ups
|
||
|
|
|
||
|
|
- **`schema-cleanup-from-scanner-audit`** — `is_system_collection` vs
|
||
|
|
`user_cards` unification (separate convoy).
|
||
|
|
- **`rename-repo-and-vercel-project`** — infra naming, not UI copy.
|