corp-v1-channel-scope/SKILL.md

---
name: corp-v1-channel-scope
description: "Use when operating or synchronizing a Corp v1 project's Scope channel. Owns Roadmap, Epics, Features, and Ideas; correlates all six same-project channels; proactively improves evidence-based product scope; and records human approval before work enters Architecture solution design."
version: 1.2.0
author: Hermes Agent
license: MIT
metadata:
  hermes:
    tags: [corp-v1, discord, channel, scope, roadmap, epics, features, discovery]
    related_skills: [corp-v1--main, home-v1-discord, documentation-docusaurus]
---

# Corp v1 Scope Channel

## Overview

This skill owns product discovery and durable scope for a Corp v1 project's `scope` channel. It monitors the six same-project channels—`general`, `scope`, `architecture`, `kanban`, `delivery`, and `releases`—and maintains the project documentation's top-level **Scope** area.

Scope owns Roadmap, Epics, Features, and Ideas. General coordinates overall project awareness but does not duplicate Scope records. Architecture performs solution work only for Features explicitly approved for solution by a human team member. Hermes participates proactively by proposing and refining useful scope, but never approves its own proposals.

Load the global `documentation-docusaurus` skill from `https://gitea.lego-cloud.eu/home-v1-skills-code-agent/documentation-docusaurus` before changing documentation structure, navigation, Markdown/MDX, Docusaurus configuration, or builds.

## When to Use

Use this skill when:

- operating in `corp-v1-<code>-scope`;
- running its recurring synchronization job;
- maintaining Roadmap, Epics, Features, or Ideas;
- discovering user/project problems and opportunities;
- refining value, scope, acceptance outcomes, dependencies, or risks;
- preparing an Epic or Feature for human `Approved for Solution` review;
- reconciling scope against architecture, Kanban, delivery, or release evidence.

Do not use it to design architecture, approve solution entry, approve implementation, admit tasks to Kanban Focus, implement code, or authorize releases.

## Approved Information Boundary

Inspect only:

```text
corp-v1-<code>-general
corp-v1-<code>-scope
corp-v1-<code>-architecture
corp-v1-<code>-kanban
corp-v1-<code>-delivery
corp-v1-<code>-releases
```

Read enough Scope history to avoid duplicates and only relevant new activity from the other five channels. Never inspect or correlate another project's channels.

## Human Approval Gate

Only a human team member may move an Epic or Feature to `Approved for Solution`. Hermes may propose, investigate, refine, deduplicate, identify dependencies, prepare acceptance outcomes, and recommend approval. Silence, an agent statement, CI success, delivery activity, or a forecast is not approval.

Record approver identity, decision evidence, date, resulting status, and conditions. Architecture may begin solution work only after this evidence exists.

## Documentation Contract

`Scope` is a top-level menu item immediately before `Architecture`, with its own dedicated sidebar:

```text
Roadmap
Epics
  <CODE>-EP-1
    <CODE>-FT-1
    <CODE>-FT-2
  <CODE>-EP-2
    ...
Ideas
```

### Roadmap

Show verified current state and predicted plans at Epic and Feature level. Distinguish approved/current facts from forecasts and proposals. Include sequence or horizon, status, dependencies, material blockers, owner, and last evidence/update date.

### Epics and Features

Use stable project-scoped IDs:

```text
Epic:    <UPPERCASE_PROJECT_CODE>-EP-<NUMBER>
Feature: <UPPERCASE_PROJECT_CODE>-FT-<NUMBER>
```

Allocate numbers monotonically. Never reuse or renumber an ID after rejection, deferral, deletion, or consolidation.

Minimum Epic fields:

```text
ID | title | problem/opportunity | intended outcome | value | status | owner | Feature links | evidence
```

Minimum Feature fields:

```text
ID | Epic | user/problem statement | expected value | scope | acceptance outcomes | status | owner | dependencies | risks | evidence
```

Each Epic page contains a linked Features table with current statuses. Each Feature page contains title, description, value, scope, acceptance outcomes, dependencies, risks, human approval evidence, and a linked table of authoritative Architecture tasks when they exist. Scope never creates duplicate task identities.

Approval is a gate, not a delivery status. Preserve `Approved for Solution`, implementation approval, conditions, and decision evidence in dedicated fields and append-only histories; do not overload the item's delivery status with approval language.

### Ideas

Ideas are early opportunities not yet accepted as Epics or Features. Record stable local reference, title, description, evidence/source, owner when known, status, and resulting Epic/Feature links. Preserve provenance after promotion.

## Unified delivery lifecycle and roll-up

Use one delivery vocabulary across Ideas, Epics, Features, and Tasks while preserving the difference between product design/delivery and task execution.

Product items use:

```text
Idea, Epic, Feature: IN_BACKLOG → IN_DESIGN → IN_DELIVERY → TO_BE_RELEASED → DONE
```

Tasks use:

```text
Task: IN_BACKLOG → IN_PROGRESS → TO_BE_RELEASED → DONE
```

`CANCELLED` is an explicit exceptional terminal state for every item type. `BLOCKED` is an orthogonal flag with a reason and evidence, never a lifecycle status. Do not use `READY`, `QUEUED`, `Proposed`, `Approved for Solution`, or `Approved for Implementation` as delivery statuses.

### Status meaning

- `IN_BACKLOG`: retained but not actively designed or executed.
- `IN_DESIGN`: an Idea, Epic, or Feature is actively being scoped, decomposed, or solutioned; no required implementation Task has started.
- `IN_PROGRESS`: a Task is actively being implemented or validated.
- `IN_DELIVERY`: implementation of a product item's governed descendant scope has started, or part of that scope is already later in the delivery chain while the complete product item has not reached `TO_BE_RELEASED`.
- `TO_BE_RELEASED`: the complete required scope is implementation-complete and belongs to a release candidate, but release verification is not complete.
- `DONE`: the complete required scope has passed its release boundary, or an explicitly non-releasable item has durable completion evidence.
- `CANCELLED`: an authorized decision removed, rejected, abandoned, or superseded the item. Cancellation never means done.

### Canonical relationships

Maintain one validated roll-up set at each boundary:

```text
Idea    → directly resulting Epics and/or Features
Epic    → required child Features
Feature → required implementation Tasks
```

When an Idea points to both an Epic and one of that Epic's Features, mark only one level as a roll-up target so the same work is not counted twice. Distinguish required children from optional, removed, or superseded children. A cancelled child may be excluded only by an explicit scope decision that updates the parent's required set; never count `CANCELLED` as `DONE`.

### Deterministic parent aggregation

Derive Idea status from its validated direct resulting-item set, Epic status from required Features, and Feature status from required Tasks. Evaluate these rules in order:

1. `CANCELLED` is never derived; it requires an explicit authorized item decision.
2. If the required-child set is non-empty and every required child is `DONE`, the parent is `DONE`.
3. Otherwise, if every required child is either `TO_BE_RELEASED` or `DONE` and at least one is `TO_BE_RELEASED`, the parent is `TO_BE_RELEASED`.
4. Otherwise, if any required descendant has entered active or later execution—Task `IN_PROGRESS`, or child `IN_DELIVERY`, `TO_BE_RELEASED`, or `DONE`—the parent is `IN_DELIVERY`.
5. Otherwise, an actively scoped, decomposed, or solutioned product item is `IN_DESIGN`.
6. Otherwise, the parent is `IN_BACKLOG`.

An item with no validated required children cannot derive `TO_BE_RELEASED` or `DONE`; require direct evidence for the exact item. A parent must never appear less advanced than an active required child. Mark every computed status with `status_source: DERIVED`; exact Task transitions and direct no-child decisions use `status_source: EXACT`.

### Transition and evidence rules

- Product items normally move `IN_BACKLOG → IN_DESIGN`; they move to `IN_DELIVERY` when required descendant implementation starts.
- Tasks normally move `IN_BACKLOG → IN_PROGRESS → TO_BE_RELEASED → DONE`.
- A Task may move directly from `IN_PROGRESS` to `DONE` only when its outcome is explicitly non-releasable or the same evidence proves implementation and release completion; record the reason.
- Moving the final required child can trigger deterministic parent roll-up in the same canonical change, but never fabricate missing relationships or evidence.
- Promotion does not finish an Idea. A promoted Idea remains linked to its resulting items and follows their aggregate delivery status until their required outcome is `DONE`.
- Documentation activity, approval, CI success, merge state, deployment health, or silence alone does not advance status. Every exact transition requires actor, authority, UTC date, previous and target state, conditions, and durable evidence.
- Keep approval, blocking, acceptance evidence, version allocation, deployment, and release records separate from lifecycle status even when they supply transition evidence.
- Preserve append-only historical approval/lifecycle events during migration. Convert old approval-shaped status fields into approval gates and establish the new delivery status with a new evidenced event; do not rewrite history.

## React Flow visualization contract

When Scope documentation contains relationship-dense data, deliberately consider a read-only `@xyflow/react` view after loading `documentation-docusaurus` and its React Flow guidance. Appropriate Scope views include:

- Epic-to-Feature composition;
- Feature-to-Feature dependencies;
- Feature-to-question readiness relationships;
- Requirement-to-Feature and Architecture-Decision-to-Feature traceability;
- roadmap sequencing and a deterministic Gantt-like timeline when approved dates and lanes exist.

Render a visualization only when the required relationships, dates, lanes, and states exist in validated canonical YAML and the graph materially improves comprehension. A small, linear, empty, or weakly connected dataset should remain a semantic table or list. A graph must not infer unapproved dependencies, dates, hierarchy, readiness, approval, critical path, or progress.

Use one typed, deterministic adapter and the same selector to produce stable nodes, edges, legends, validation warnings, and an adjacent semantic table fallback. Generated graph data, coordinates, viewport state, and client state are derived presentation data, never a second source of truth. Preserve exact relationship semantics: questions, blockers, dependencies, decisions, approval conditions, and readiness are distinct concepts and edge types.

Use Dagre for ordinary directed graphs and ELK only for complex or grouped graphs. Derive Gantt-like positions deterministically from approved dates and lanes. Use Docusaurus `BrowserOnly` where client-only rendering is required, while keeping the semantic fallback server-renderable, searchable, linkable, and usable if JavaScript or hydration fails.

Documentation canvases are read-only. Disable mutation affordances, including `nodesDraggable={false}`, `nodesConnectable={false}`, connection creation, deletion, and accidental persistence. Preserve keyboard navigation, meaningful accessible labels and authoritative-record links, visible focus, non-color-only meaning, reduced-motion behavior, responsive controls, and sharp styling with `border-radius: 0`.

Acceptance requires canonical-YAML validation, graph/table parity from the same selector, stable deterministic output, missing-reference failure or explicit warning behavior, empty/loading/error states, keyboard and screen-reader checks, no-JavaScript fallback, production build, browser console/network health, and remote exact-head verification. React Flow supplements the Roadmap, Epic/Feature records, and semantic tables; it never replaces governed Scope records.

## Proactive Iteration Requirement

Every Scope iteration must add or materially improve at least one evidence-based scope artifact when a safe path exists: a grounded Idea, Epic, or Feature; clearer value or acceptance outcomes; dependency/risk evidence; deduplication; Roadmap reconciliation; cross-links; or a concrete unanswered product question. Never create filler to satisfy cadence.

Use evidence from all six same-project channels. Delivery and release outcomes may expose new Ideas or required scope corrections; Architecture may expose infeasible assumptions; Kanban may expose flow or dependency problems. Preserve authority boundaries while incorporating that evidence.

## Handoffs

- **Scope → Architecture:** only human-approved Features with stable ID, parent Epic, value, scope, acceptance outcomes, dependencies, risks, and approval evidence.
- **Architecture → Scope:** feasibility constraints, requirement implications, dependencies, and proposed scope clarifications; Architecture does not silently rewrite product scope.
- **Scope → Kanban:** stable Epic/Feature identities and lifecycle state for Board/Focus reconciliation.
- **Delivery/Releases → Scope:** verified outcomes, regressions, user feedback, and follow-up opportunities that may alter the Roadmap or create Ideas.
- **Scope → General:** concise overall implications, decisions requiring visibility, owners, and cross-channel blockers.

## Synchronization Workflow

1. Confirm the exact project code and six approved channel IDs.
2. Read new activity from the other five channels and enough Scope history to avoid duplication.
3. Separate verified facts, human decisions, proposals, forecasts, and unresolved questions.
4. Inspect Roadmap, Epics, Features, Ideas, links, IDs, lifecycle states, and approval evidence.
5. Reconcile architecture feasibility, Kanban flow, delivery progress, and release outcomes against scope.
6. Add or materially improve at least one useful evidence-based artifact, or document the exact evidence/approval blocker.
7. Load `documentation-docusaurus`, validate menu order, dedicated sidebar, hierarchy, links, and documentation build, then verify remote state.
8. Post a concise Scope update with changed artifacts, implications, human gate, and exact evidence. Stay silent when no substantive result exists.

## Authority and Escalation

May autonomously:

- summarize verified same-project scope implications;
- propose and refine Ideas, Epics, and Features;
- maintain Roadmap mechanics, links, IDs, and evidence;
- record explicit human decisions;
- run read-only checks and documentation validation;
- repair clear non-semantic documentation defects.

Requires human approval for:

- moving an Epic or Feature to `Approved for Solution`;
- materially accepting/rejecting product scope;
- changing governance, architecture, implementation, version, or release decisions;
- permissions, credentials, spending, external contact, or irreversible/high-impact work.

## Common Pitfalls

1. Treating General as the authoritative owner of Scope records.
2. Approving a proposal because nobody objected.
3. Creating Epics or Features without evidence, value, acceptance outcomes, owner, or dependencies.
4. Using generic IDs instead of project-scoped stable IDs.
5. Duplicating Architecture task records in Scope.
6. Mixing approved/current state with predictions in the Roadmap.
7. Ignoring Architecture, Kanban, Delivery, or Releases evidence.
8. Inspecting another project's channels.
9. Posting repetitive status instead of improving durable documentation.
10. Claiming completion without build and remote readback evidence.
11. Treating approval names as delivery statuses instead of separate gates.
12. Marking an Idea `DONE` merely because it was promoted, rather than rolling up its governed resulting items.
13. Deriving a parent from an incomplete, duplicated, or unvalidated child set.
14. Counting a cancelled child as done or silently excluding it without an explicit scope decision.
15. Moving a parent to `TO_BE_RELEASED` while any required child remains in backlog, design, active delivery, or progress.

## Verification Checklist

- [ ] Only the six same-project channels were inspected.
- [ ] Scope appears immediately before Architecture with its own sidebar.
- [ ] Sidebar order is Roadmap, Epics with nested Features, then Ideas.
- [ ] Roadmap distinguishes verified current state from predicted plans.
- [ ] Epics and Features use stable project-scoped IDs and valid parent-child links.
- [ ] Every Epic links child Features; every Feature links authoritative tasks when present.
- [ ] Ideas preserve provenance when promoted.
- [ ] Every item uses the governed status vocabulary for its type; approval, blocking, and release evidence remain separate fields.
- [ ] Idea, Epic, and Feature roll-ups use complete validated required-child sets with no ancestor/descendant double counting.
- [ ] Every derived status follows the ordered aggregation rules and is labelled `DERIVED`; exact transitions are labelled `EXACT`.
- [ ] No parent is `TO_BE_RELEASED` or `DONE` while a required child is earlier than that aggregate permits.
- [ ] At least one useful artifact was improved, or an exact evidence/approval blocker was recorded.
- [ ] No Epic or Feature entered `Approved for Solution` without explicit human evidence.
- [ ] Architecture handoff contains value, scope, acceptance outcomes, dependencies, risks, and approval evidence.
- [ ] Documentation build, links, and remote readback passed.
- [ ] When React Flow is used, its graph and semantic table share one canonical-YAML selector and pass accessibility, build, browser, and remote exact-head checks.
- [ ] Completed work includes exact message, path, commit, URL, or run evidence.