Skip to content

docs(rfc): upkeep guidance for a crewmate's Dashboard fields - #19043

Merged
iamwhatever merged 2 commits into
mainfrom
docs/rfc-mate-operating-guide
Oct 12, 2026
Merged

iamwhatever merged 2 commits into
mainfrom
docs/rfc-mate-operating-guide

Conversation

@iamwhatever

@iamwhatever iamwhatever commented Oct 11, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: Record the decision that every crewmate with a Dashboard page is told, by dashboard_fields, what each field only it can fill means, when to write it and how, with a generated helper script where the data lives outside the crew log, named by one pointer line that survives compaction and readable on the profile.

A crewmate that adopts a Dashboard page is told which fields are its own and never what they mean, when to write them, or how to get the data. The whole instruction is the [DASHBOARD] block from dashboard_agentic.turn_block: the template id and "Fields you write: ...". So fields go unwritten, or stay stale until the person chases them. A field like ci is worse: its data is on GitHub, and the crewmate works out the gh calls and the payload shape every time.

[CURRENT ASSIGNMENT] (members/<slug>/briefing.md) cannot carry this: it is agent-written, may be empty, and a crewmate with no file tools cannot write it. The person also cannot see what the crewmate is told about its page.

Why it matters

The Dashboard tab is what a person reads when they are not reading the thread. A stale field there is a wrong answer shown with authority, and today the only fix is the person noticing and asking.

The implementation adds a line to every crewmate's prompt and a section to the profile. The First Principles lane reads that decision off the base branch, so it lands here first.

Not a goal

  • Shipping code. This pull request changes two files under docs/request-for-change/ and nothing else.
  • Anything for fold-backed fields: they already update themselves from the manifest ({fold, path}).
  • The hand-published drawer (panel_publish). fix(crew): draw the conductor's drawer board from its work ledger #18957 makes the conductor's drawer fold-backed.
  • Helpers for an agent-composed v3 package, which carries no code.

What changed (motivation → approach → change)

New docs/request-for-change/rfc-crewmate-dashboard-upkeep-skill.md (status in-progress) and its row in the RFC index. It records the product owner's ruling of 2026-10-11, revised in review on 2026-10-12, and replaces this PR's first draft (an [OPERATING GUIDE] text block).

  • Prior art (§2). A {"fold", "path"} field is filled by the gateway from the crew log, in both formats: dashboard_templates/manifest.py _field and artifact_store/dashboard_package.py _validate_source. So the gap is exactly the {"agentic": true} fields.
  • Manifest key (§4.1). An agentic field may declare upkeep: {means, when, how, helper?}. Every built-in agentic field gets one. project-report.ci and pr-watch.lanes name a helper.
  • Upkeep text in dashboard_fields (§4.2). Each agentic row of the dashboard_fields reply (dashboard_agentic.fields_for_agent) gains an upkeep object, read from the shipped catalog when the tool is called, never from the crewmate's writable copy. It is a tool reply, so a crewmate with no file tools reads it too, and nothing is generated for the text.
  • Helper script (§4.3). A copy of a shipped builtin/<id>/helpers/<file> under .dashboard-upkeep/<slug>/scripts/, the only thing in that directory. It runs gh and prints a ready dashboard_write payload. Only shipped built-ins may name one. A crewmate with no shell writes the field from what it can read instead. A test checks each helper's output passes check_write.
  • Script regeneration (§4.4). dashboard_upkeep.sync(slug) copies the helpers, writing only what differs, from instance._commit (adopt, apply, rollback, edit) and from the [DASHBOARD] build (default page, gateway upgrade). Those are every trigger that changes which helpers apply; a v3 package names none.
  • Pointer (§4.5). One line at the end of [DASHBOARD] naming the upkeep text in dashboard_fields. It rides the member section's three legs (fresh, post-compaction, slim resume). Apply and rollback replies carry it too.
  • Profile (§4.6). GET /api/members/{slug}/briefing gains upkeep: {pointer, fields, scripts}; the Notes tab shows it read-only.
  • Rejected (§5). Guide text only; a generated SKILL.md per board (a crewmate with no file tools cannot open it); one generic manifest-driven update script; a script per board; writing upkeep into [CURRENT ASSIGNMENT].

Backwards compatibility

Compatible: documentation only.

Removes nothing: the diff adds one document and one index row.

Tests

N/A — documentation only. python3 scripts/docs_lint.py passes.

Manual verification

N/A — documentation only. Every symbol cited was read at a84f616557 and re-read at 0cda1525d8.

Related Issues

Part of #19481 (the implementation PR in the RFC's §7 step 2).

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

Contribution License Agreement

Contributions are accepted under the project's Apache-2.0 license.

@iamwhatever
iamwhatever requested review from a team and KiroCrewCaptain as code owners October 11, 2026 05:46
@iamwhatever
iamwhatever requested a review from buluoray October 11, 2026 05:46
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Oct 11, 2026
@github-actions

github-actions Bot commented Oct 11, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — 🟡 CONCERNS

Premise-level review of 3877be72d60722db7dae251fec8846d08c941fe8 — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

First-Principles-Verdict: CONCERNS

The RFC lands as in-progress with no implementation PR. Its new pointer line repeats an instruction [DASHBOARD] already gives.

Not justified as shipped

  • Item 2 — inherited: the index row says "Nothing yet", the front matter says implementation-prs: [], and the status is still in-progress. Other rows use in-progress only "against the open PR that carries it". Here the ruling is an unnamed "product owner's ruling of 2026-10-11". Once this merges, later First Principles runs will treat that as a recorded decision.
    Subtraction: change the status to draft.
    Clears when: a named maintainer's acceptance is quoted in the document, or the status reads draft.
  • Item 3 — duplicate of src/kiro_crew/dashboard_agentic.py:867 (1 hit for Call dashboard_fields): the line "Call dashboard_fields for their shapes and current values before dashboard_write" already sends the crewmate to the same read at the same moment. The proposed "read it before you write a field" adds a second spelling to every prompt. It also puts the when text behind a read the crewmate makes only after deciding to write, so a field nobody decides to write stays unwritten.
    Subtraction: delete the separate Upkeep: line from §4.5.
    Clears when: §4.5 drops the pointer, or names a failing case the existing sentence misses.

What this change ships

Inventory (6 items) — 4 justified

Intent: record the design decision for telling crewmates how to keep their Dashboard fields current. ADDITION (docs only).

  1. New RFC defining per-field upkeep text served by dashboard_fields — justified
  2. The RFC lands as in-progress with no implementation PR — inherited
  3. A proposed extra pointer line in every crewmate's [DASHBOARD] block — duplicate of dashboard_agentic.py:867
  4. Proposed helper scripts copied from shipped built-ins — justified
  5. Proposed upkeep section on the profile's Notes tab — justified
  6. New row in the RFC index — justified

[FIRST-PRINCIPLES-REVIEWED] 3877be7

Description read

[DESCRIPTION-READ] cf3a774080a962ccff9ef6829ae5228841c06525d8818b98b33c9a6284597f32

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

github-actions Bot commented Oct 11, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ✅ PASS

UX-level review of 3877be72d60722db7dae251fec8846d08c941fe8 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

UX-Verdict: PASS

Nothing to check.

[UX-REVIEWED] 3877be7

Description read

[DESCRIPTION-READ] 3d030657cc8bbec968a9954841880951ac04351b6295b69149a2ccc53e3b00c2

That sha256 names everything this verdict read: the PR description, plus the 7 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@iamwhatever
iamwhatever force-pushed the docs/rfc-mate-operating-guide branch from 4c7db82 to 6710ece Compare October 11, 2026 05:48
@github-actions

github-actions Bot commented Oct 11, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of 3877be72d60722db7dae251fec8846d08c941fe8 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 3877be7

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 3877be72d60722db7dae251fec8846d08c941fe8: <one-sentence reason>

@github-actions

github-actions Bot commented Oct 11, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — 🟡 CONCERNS

Design-level review of 3877be72d60722db7dae251fec8846d08c941fe8 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: CONCERNS

The helper copy in §4.3 is the only reason §4.4's sync machinery exists, and it puts filesystem writes into the [DASHBOARD] prompt build.

Watch

  • §4.3 says the helper is "a COPY of the shipped file dashboard_templates/builtin/<id>/helpers/<helper>" in an agent-writable skills dir. Because it is a copy, §4.4 needs dashboard_upkeep.sync, which has to remove stale helpers, undo hand edits and pick up upgraded bytes. To catch the default page and gateway upgrades, §4.4 also calls sync from "the [DASHBOARD] block build". Session start, post-compaction and slim resume would then do disk I/O and could fail there. The RFC gives no failure story for that path: what happens to the turn if the copy can't be written?
  • A simpler option: dashboard_fields names the shipped helper's installed path, or a python -m kiro_crew… invocation. That is read-only, can't drift and needs no sync callers. §5 doesn't consider it.
    Clears when: §5 rejects "point at the shipped helper path" and says why (for example, the sandbox can't read the package path), or §4.4 states that a failed sync never blocks or fails the [DASHBOARD] build.

[DESIGN-REVIEWED] 3877be7

Description read

[DESCRIPTION-READ] d7ca7c99e7d2a1bf5a845caf2fde9e56dd26d8a040411d244aba8d8d3918cd18

That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Oct 11, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed 3877be72d60722db7dae251fec8846d08c941fe8 — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 3877be7

Verdict parsed from the review's SHA-scoped output markers for commit 3877be72d60722db7dae251fec8846d08c941fe8.

False positive or not applicable? A repository writer can comment:
/ai-review override fable 3877be72d60722db7dae251fec8846d08c941fe8: <one-sentence reason>

@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision merge conflict Branch has merge conflicts with its base — author must resolve before merge and removed readiness: checking Automated validation is still running labels Oct 11, 2026
@iamwhatever iamwhatever changed the title docs(rfc): a system-owned operating guide for a crewmate's Dashboard page docs(rfc): a generated upkeep skill for a crewmate's Dashboard fields Oct 11, 2026
@iamwhatever
iamwhatever force-pushed the docs/rfc-mate-operating-guide branch from 6710ece to dc4c8db Compare October 11, 2026 07:40
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: passed Eligible automated validation passed for the current revision merge conflict Branch has merge conflicts with its base — author must resolve before merge labels Oct 11, 2026
@iamwhatever
iamwhatever force-pushed the docs/rfc-mate-operating-guide branch from dc4c8db to ae8648c Compare October 11, 2026 07:53
@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Oct 11, 2026
chenmingwei23
chenmingwei23 previously approved these changes Oct 11, 2026
@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Oct 11, 2026
@iamwhatever
iamwhatever force-pushed the docs/rfc-mate-operating-guide branch from ae8648c to 1cb412e Compare October 12, 2026 06:04
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: passed Eligible automated validation passed for the current revision merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: checking Automated validation is still running labels Oct 12, 2026
@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Oct 12, 2026
@iamwhatever
iamwhatever force-pushed the docs/rfc-mate-operating-guide branch from d17a774 to 43f5849 Compare October 12, 2026 11:49
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision and removed readiness: passed Eligible automated validation passed for the current revision readiness: checking Automated validation is still running merge conflict Branch has merge conflicts with its base — author must resolve before merge labels Oct 12, 2026
@iamwhatever

Copy link
Copy Markdown
Contributor Author

Self-review (crew-pr-reviewer, read-only): CHANGES NEEDED

This RFC records the decision to give each crewmate a generated upkeep skill for its agentic Dashboard fields. The motivating gap is real: the [DASHBOARD] block names the fields but never says what they mean or how to fill them. I read the full document, the lane comments on head 43f5849 and the author's disposition. The Design lane's CONCERNS is legitimate and still open in the text. The RFC rejects [CURRENT ASSIGNMENT] because "a crewmate with no file tools cannot write it" (rfc-crewmate-dashboard-upkeep-skill.md:51 and the §5 table at :208). Yet its own route is a pointer to read .dashboard-upkeep/<slug>/SKILL.md and, for ci/lanes, to run a gh helper. That file is kept out of the skill index on purpose, so that same crewmate cannot follow the pointer either, and its fields stay stale, which is the harm the RFC exists to remove. The posted disposition leaves this to "the RFC review", but this PR is that review, and it names an older head (d17a774) with no ai-review-disposition marker. Suggested fix: in §4.2/§4.5, have dashboard_fields (already named in the [DASHBOARD] block) return each field's upkeep means/when/how, and keep the generated directory for the helper scripts only. Otherwise, drop "no file tools" as the rejection reason at :51 and :208. Please also add an issue line (Part of #N) for the follow-up implementation. — crew-pr-reviewer

@iamwhatever
iamwhatever marked this pull request as draft October 12, 2026 15:47
@iamwhatever

Copy link
Copy Markdown
Contributor Author

Converted to draft by crew-pr-reviewer: the self-review above is CHANGES NEEDED. Mark ready again (gh pr ready 19043) once the points are addressed.

@github-actions github-actions Bot added readiness: checking Automated validation is still running merge conflict Branch has merge conflicts with its base — author must resolve before merge and removed readiness: passed Eligible automated validation passed for the current revision labels Oct 12, 2026
@iamwhatever
iamwhatever force-pushed the docs/rfc-mate-operating-guide branch from 43f5849 to 7200611 Compare October 12, 2026 16:41
@github-actions github-actions Bot removed the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Oct 12, 2026
@iamwhatever iamwhatever changed the title docs(rfc): a generated upkeep skill for a crewmate's Dashboard fields docs(rfc): upkeep guidance for a crewmate's Dashboard fields Oct 12, 2026
@iamwhatever

Copy link
Copy Markdown
Contributor Author
  • Delivery needs a capability the RFC says some crewmates lack.

Outcome: fixed in 3877be72d.
§5 now weighs serving upkeep through dashboard_fields and adopts it: §4.2 adds an upkeep object to each agentic row of the dashboard_fields reply, read from the shipped catalog, and the generated SKILL.md is listed as rejected because a crewmate with no file tools cannot open it. §4.3 says what a crewmate with no shell does for ci / lanes: it writes the lane states it can read in the shape dashboard_fields gives, through the same dashboard_write checks.

@iamwhatever

Copy link
Copy Markdown
Contributor Author
  • A generated copy on disk needs a sync job that can drift.

Outcome: fixed in 3877be72d.
The upkeep text is no longer copied: dashboard_fields reads it from the catalog when called (§4.2), so it has no copy to drift. Only the shipped helper scripts are copied, and §4.4 now names every trigger that changes which helpers apply: a commit (adopt, apply, rollback, edit), the default page taking effect with no commit, and a gateway upgrade changing a helper's bytes. A v3 package (#18707, §7 step 3) names no helper, so that path adds no trigger.

@iamwhatever

Copy link
Copy Markdown
Contributor Author

Reply to the crew-pr-reviewer self-review (CHANGES NEEDED), addressed in 3877be72d:

  1. The "no file tools" rejection vs a pointer to a file. Took the suggested fix. §4.2 now has each agentic row of dashboard_fields (dashboard_agentic.fields_for_agent) return upkeep: {means, when, how, helper?}, read from the shipped catalog when the tool is called. No SKILL.md is generated; .dashboard-upkeep/<slug>/scripts/ holds the helper scripts only (§4.3). The pointer line (§4.5) now names dashboard_fields, and the profile key (§4.6) carries the same per-field text. §4.3 says what a crewmate with no shell does for ci / lanes. §5 records the generated-SKILL.md design as rejected for the reason you gave, so the "no file tools" argument at §1 and §5 now holds for the chosen route too.
  2. Stale disposition on d17a77403c with no marker. Replaced by two ai-review-disposition target=design comments on 7200611c2, the head the Design lane last reviewed, one per concern.
  3. Issue line. Opened Crewmate Dashboard upkeep: per-field upkeep text in dashboard_fields and helper scripts #19481 for the implementation PR (§7 step 2). The PR body says Part of #19481, and the RFC front matter and index row track it.

The RFC index sentence records the 2026-10-12 revision. python3 scripts/docs_lint.py passes.

@iamwhatever
iamwhatever marked this pull request as ready for review October 12, 2026 17:44
@iamwhatever

Copy link
Copy Markdown
Contributor Author

Pure RFC changes, which gives the crew mate instructions to update fields in the dashboard/panel.

@iamwhatever
iamwhatever merged commit e0578ed into main Oct 12, 2026
88 of 104 checks passed
@iamwhatever
iamwhatever deleted the docs/rfc-mate-operating-guide branch October 12, 2026 18:07
@github-actions github-actions Bot removed the readiness: checking Automated validation is still running label Oct 12, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants