Prototype a Claude skill that drafts Hiero's LFDT TAC report from the data API

🧑‍💻 Intermediate Issue — a complex task spanning multiple modules, with real design decisions to own.
Time: ~25 hours · Prerequisites: comfortable navigating this repo (a completed beginner issue is the usual route; demonstrated CI/CD proficiency substitutes for workflow-focused issues).
We expect more than "it works": maintainable code that fits the existing architecture.

The task

Problem:

Hiero reports to the LF Decentralized Trust TAC twice a year: an annual review and a mid-year update, filed in LF-Decentralized-Trust/governance under tac/project-updates/ — read that directory (especially annual-review-instructions.md) before designing anything. The annual review asks five questions: progress against last year's goals, deliverables, next year's goals, help needed, and maintainer/contributor diversity — plus supporting evidence on contribution activity, adoption, and governance health.

Three of those five questions and most of the evidence are data this repository already publishes as public JSON: the dashboard's data API at https://hiero-hackers.github.io/analytics/data/api/v1/manifest.json lists per-org section documents covering affiliations and diversity, maintainer load share, inactive-maintainer detection, CODEOWNERS coverage, release staleness, and HIP progress — each with methodology notes explaining how the numbers were computed. But today nobody consumes this API except the dashboard itself, and assembling a TAC report from it is manual work.

We want a Claude skill that drafts the report from the API. It has a second job that is just as important as the draft: it is the instrument that discovers, with evidence, what the API layer is missing — the input for follow-up API work.

What done looks like:

A repo skill at .claude/skills/lfdt-report/ (SKILL.md, plus whatever reference files the design needs). .claude/skills/write-analytics-issue/ is the house pattern for repo skills — match its tone and structure.
Inputs: report type (annual | mid-year) and org (default hiero-ledger). It fetches manifest.json from the live API above and walks the section/view documents the manifest lists — no hard-coded file lists, so new sections appear in reports without skill changes.
Output: a Markdown draft following the TAC report structure. Data-backed sections are filled with real numbers and link back to the live dashboard as evidence; the human-judgment sections (goals, help needed) are rendered as clearly marked > [MAINTAINER INPUT] slots, never invented.
A Data Gaps appendix: every fact the report wants but cannot get from the API (expected examples: contribution-activity trends over time, OpenSSF scorecard values, "since last report" deltas — these exist in pipelines but are currently published only as chart PNGs) is recorded and emitted at the end of the draft. This appendix is a first-class deliverable, not an error log.
Exercised, not just written: generate a real draft of Hiero's next report and attach it to your PR, reviewed by you against the TAC instructions. Also exercise the edge cases: the mid-year type, the hiero-hackers org (which lacks several tabs the skill will look for), and an unreachable API.
This issue makes zero changes to the API or pipelines. If the skill needs data the API lacks, that goes in the gap appendix — filling gaps is deliberate follow-up work, not scope here.

Modules involved / constraints:

You need access to Claude Code (CLI, desktop, or claude.ai/code) to run and iterate on the skill — authoring is plain Markdown, but the deliverable must be tested by actually invoking it. Say so in your approach comment if that's a blocker.
.claude/skills/write-analytics-issue/SKILL.md — the existing repo skill to model yours on.
web/src/api.ts — the most complete documentation of the API contract (manifest, section docs, views, metric tiles); the doc comments there are the field glossary your skill needs.
The API is static JSON on GitHub Pages — no auth, no rate concerns, but also no queries: the skill composes from documents as published.
Design decisions you own (propose before coding): how the skill maps API sections onto the TAC questions, how the gap appendix is structured, and whether a sample draft is committed to the repo or only attached to the PR.
Related, not overlapping: Render any tab as a clean printed document for TSC meetings #356 wants a printable document view of dashboard tabs (different deliverable, same audience); Ingest releases per repo: cadence chart and staleness columns #331 (release ingestion) will likely appear in your gap appendix — reference it there rather than waiting on it.

How to work on this

Claim it: comment /assign and wait to be assigned — unassigned PRs are closed automatically.
Get a plan: once assigned, comment @coderabbitai plan for a draft plan, then do your own investigation — docs/architecture.md maps the layers and their rules.
Propose your approach as a comment before coding. A paragraph is enough; early feedback here routinely saves days of rework.

🤖 AI: tools are welcome; verified work is required — you can explain every line and defend every design choice. See the AI policy. Fully automated bot PRs are closed.

Worth knowing about this repo before you design:

The layer rules in docs/architecture.md are strict — review will hold your solution to them.
Tests mirror src (tests/<pkg>/test_<module>.py), and the output-contract test pins the pipeline output surface — this issue should not touch that surface; if your design somehow does, stop and re-scope.

Before opening your PR:

I proposed my approach on this issue and incorporated any feedback
The solution fits the existing architecture and layer rules, and is clear enough for others to debug without me
Tests cover the happy path, edge cases, and error handling (testing guide) — for this skill, that means the exercised runs listed above, with the drafts attached
I reviewed my own diff line by line; scope is limited to this issue
Workflow checks pass — CI green, signed commits, linked issue

Stuck? Comment here with what you've tried — see getting help.

Coding Plan

Summary

Treat the deliverable as a documentation-only Claude Code skill that models the existing write-analytics-issue house pattern: a SKILL.md with a numbered imperative workflow plus small reference files.

Drive the report dynamically from manifest.json and the section/view documents it lists. Use web/src/api.ts as the field glossary. Hard-code no file lists.

Fill data-backed TAC sections with cited real numbers and dashboard links. Render goals and help-needed as > [MAINTAINER INPUT] slots. Emit a first-class Data Gaps appendix for every fact the API cannot supply.

Exercise the skill against the live API for the annual/hiero-ledger primary case and the mid-year, hiero-hackers, and unreachable-API edge cases. Confirm the change touches no code or contract surface.

Design Choices

Design Choice 1: How the skill handles "since last report" deltas

Options Considered:

Treat "since last report" deltas purely as a data gap and record them in the appendix.
Instruct the skill to read the data/snapshots branch via git to compute deltas.

Chosen Option: 1

Rationale: The API is static JSON with no query capability. A historical archive exists on the data/snapshots git branch (see docs/snapshots.md), but it is a git resource, not an API document. The ticket scopes the skill to API-only consumption. The appendix must record the delta gap and cross-reference docs/snapshots.md and issue #331 as the follow-up path.

Design Choice 2: Should a generated sample draft be committed to the repository?

Options Considered:

Attach generated drafts to the PR only; keep the skill directory free of generated artifacts.
Commit one sample draft under the skill directory as a labeled example.

Chosen Option: 2

Rationale: The ticket asks for an exercised, reviewable artifact. A checked-in example documents the expected output shape for reviewers. Commit one clearly-labeled sample draft under .claude/skills/lfdt-report/examples/, and mark it as a point-in-time example, not a maintained file.

Design Choice 3: Does "release staleness" exist as an API-published metric?

Options Considered:

Map a TAC evidence item onto a release-staleness section.
Record release staleness as a data gap.

Chosen Option: 2

Rationale: No release-staleness concept exists in dashboard_spec or the pipelines. The skill must record it as a gap and reference issue #331 (release ingestion).

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Ground the design in the TAC instructions and the API contract

This phase produces the design inputs the skill needs. It resolves how each TAC question maps onto API data, what data is available as JSON versus PNG-only, and how the gap appendix is structured. No skill prose is written yet. This phase produces a mapping reference and a report template that later phases encode into the skill.

Task 1: Capture the TAC report requirements

Establish the required structure for both report types so the skill drafts against the real instructions.

Read the live LF-Decentralized-Trust/governance directory tac/project-updates/, especially annual-review-instructions.md and mid-year-update-instructions.md.
Record the annual review's five questions: progress against last year's goals, deliverables, next year's goals, help needed, and maintainer/contributor diversity, plus supporting evidence on contribution activity, adoption, and governance health.
Record the mid-year update's questions: progress toward yearly goals, recent deliverables, second-half goals, help needed, and changes in diversity.
Record the file-naming and navigation conventions (tac/project-updates/<year>/YYYY-annual-Project-Name.md, YYYY-MidYear-Project-Name.md, mkdocs.yml navigation entry) as output-format guidance the skill must print.

Task 2: Build the TAC-question-to-API-section mapping

Create the mapping reference that drives which manifest data fills which report section.

Create a reference file in .claude/skills/lfdt-report/ that maps each TAC question and evidence item to the API macro(s) and section id(s) that supply it.
Map maintainer/contributor diversity to the Governance affiliations and diversity sections (affiliations, committeraffiliations, repodiversity, committerrepodiversity, teamdiversity) and the Governance metric tiles.
Map governance-health evidence to loadshare (review load share), gonedark and understaffed (inactive-maintainer detection), and the Security codeowners section (CODEOWNERS coverage).
Map adoption and roadmap evidence to the HIPs sections (hip-no-activity, hip-evidence, hip-unknown) and HIP views (hip-matrix, hip-board).
State clearly in the mapping that section documents carry description, not methodology. methodology arrays live only on chart cards (ChartSpec.methodology) and metric tiles (MetricTile.methodology). The skill must cite methodology from metric tiles and section descriptions, and treat chart-only methodology as evidence of a PNG-only gap.

Task 3: Define the report template and gap appendix structure

Produce the skeleton the skill fills and the appendix format.

Create a report-template reference file in .claude/skills/lfdt-report/ with the annual and mid-year section skeletons derived from Task 1.1.
Define the > [MAINTAINER INPUT] slot convention for human-judgment sections (next year's / second-half goals, help needed). The skill must never invent values for these slots.
Define the Data Gaps appendix structure: one row or entry per missing fact, each recording the wanted fact, the TAC question it serves, why the API cannot supply it (PNG-only chart, no JSON section, no query capability), and a follow-up pointer.
Pre-seed the appendix with the examples the ticket names: contribution-activity trends over time (chart-only), OpenSSF scorecard values (chart-only, never saved as CSV), "since last report" deltas (Assumption 1), and release staleness (Assumption 3, cross-reference #331).

🤖 Prompt for AI agents

Implement Phase 1 as a research and design phase. Produce no skill prose yet;
produce the mapping reference and report template that later phases will encode
into the skill.

Step 1 - Capture the TAC report requirements:
- Read the live `LF-Decentralized-Trust/governance` directory
`tac/project-updates/`, in particular `annual-review-instructions.md` and
`mid-year-update-instructions.md`.
- Record the annual review's five questions: progress against last year's goals,
deliverables, next year's goals, help needed, and maintainer/contributor
diversity. Also record the supporting evidence categories: contribution
activity, adoption, and governance health.
- Record the mid-year update's questions: progress toward yearly goals, recent
deliverables, second-half goals, help needed, and changes in diversity.
- Record the file-naming and navigation conventions:
`tac/project-updates/<year>/YYYY-annual-Project-Name.md`,
`YYYY-MidYear-Project-Name.md`, and the `mkdocs.yml` navigation entry. Treat
these as output-format guidance for the skill to print.

Step 2 - Build the TAC-question-to-API-section mapping:
- Create a reference file in `.claude/skills/lfdt-report/` mapping each TAC
question and evidence item to the API macro(s) and section id(s) that supply it.
- Map maintainer/contributor diversity to `affiliations`,
`committeraffiliations`, `repodiversity`, `committerrepodiversity`,
`teamdiversity`, and the Governance metric tiles.
- Map governance-health evidence to `loadshare`, `gonedark`, `understaffed`, and
the Security `codeowners` section.
- Map adoption and roadmap evidence to `hip-no-activity`, `hip-evidence`,
`hip-unknown`, and views `hip-matrix`, `hip-board`.
- State explicitly that section documents carry `description`, not
`methodology`; `methodology` exists only on `ChartSpec.methodology` and
`MetricTile.methodology`. The skill must cite methodology only from metric tiles
and section descriptions, and treat chart-only methodology as a PNG-only gap.

Step 3 - Define the report template and gap appendix structure:
- Create a report-template reference file in `.claude/skills/lfdt-report/` with
annual and mid-year section skeletons derived from Step 1.
- Define the `> [MAINTAINER INPUT]` slot convention for human-judgment sections
(next year's / second-half goals, help needed); the skill must never invent
values for these slots.
- Define the Data Gaps appendix structure: one entry per missing fact, recording
the wanted fact, the TAC question it serves, the reason the API cannot supply it
(PNG-only chart, no JSON section, no query capability), and a follow-up pointer.
- Pre-seed the appendix with: contribution-activity trends over time
(chart-only), OpenSSF scorecard values (chart-only, never saved as CSV), "since
last report" deltas, and release staleness (cross-reference issue `#331`).

Phase 2: Author the skill

This phase writes the skill files. It encodes the Phase 1 design into a SKILL.md that matches the house pattern, plus the reference files. The skill fetches the manifest, walks the documents it lists dynamically, fills data-backed sections, marks human-judgment slots, and emits the gap appendix.

Task 1: Write SKILL.md

Author the main skill file following the write-analytics-issue house pattern.

Create .claude/skills/lfdt-report/SKILL.md with YAML frontmatter: name: lfdt-report and a description that states what the skill does and includes an explicit "Use whenever…" trigger clause for drafting or refreshing an LFDT TAC report.
Write a stakes intro that states the skill's dual purpose: draft the report, and discover with evidence what the API layer is missing.
Write a numbered imperative workflow: read the live TAC instructions first; take inputs (report type annual | mid-year, org default hiero-ledger); fetch manifest.json from the live API; walk the sections, views, and metrics the manifest lists with no hard-coded file lists; map data to TAC questions using the mapping reference; fill data-backed sections with real numbers and dashboard evidence links; render human-judgment sections as > [MAINTAINER INPUT] slots; record every unfillable fact in the Data Gaps appendix; review the draft against the TAC instructions before finishing.
Reference web/src/api.ts as the live field glossary for Manifest, SectionDoc, ViewDoc, and MetricTile, following the house convention of pointing to live repo files rather than duplicating their content.
Add hard rules matching the house tone: never invent maintainer-input values; never invent numbers not present in a fetched document; cite the source section id and dashboard link for every stated number.

Task 2: Add the reference files to the skill directory

Place the Phase 1 artifacts alongside SKILL.md.

Add the TAC-question-to-API-section mapping file (from Task 1.2) to .claude/skills/lfdt-report/.
Add the report-template and gap-appendix reference file (from Task 1.3) to .claude/skills/lfdt-report/.
Ensure SKILL.md references each reference file by relative path at the workflow step that uses it.

Task 3: Encode edge-case and error handling in the workflow

Make the skill handle the required edge cases explicitly.

Add a workflow step for the mid-year report type that selects the mid-year skeleton and its narrower question set.
Add a workflow step for orgs with absent macros: when the selected org's manifest entry has no sections, chart_sections, or views for a macro (the hiero-hackers case for Governance, HIPs, and Community), the skill must read manifest.macro_absent_notes for the human-readable justification and record the absence in the report and appendix rather than emitting a blank section.
Add a workflow step for an unreachable API: if manifest.json cannot be fetched, the skill must stop, report the failure clearly, and produce no partial or fabricated draft.

🤖 Prompt for AI agents

Implement Phase 2 by writing the skill files that encode the Phase 1 design.

Step 1 - Write `.claude/skills/lfdt-report/SKILL.md`:
- Add YAML frontmatter with `name: lfdt-report` and a `description` that states
the skill's purpose and includes an explicit "Use whenever…" trigger clause for
drafting or refreshing an LFDT TAC report.
- Write a stakes intro that states the skill's dual purpose: draft the report,
and discover with evidence what the API layer is missing.
- Write a numbered imperative workflow with these steps in order: read the live
TAC instructions first; take inputs (report type `annual` | `mid-year`, org
default `hiero-ledger`); fetch `manifest.json` from the live API; walk the
`sections`, `views`, and `metrics` the manifest lists, with no hard-coded file
lists; map data to TAC questions using the mapping reference; fill data-backed
sections with real numbers and dashboard evidence links; render human-judgment
sections as `> [MAINTAINER INPUT]` slots; record every unfillable fact in the
Data Gaps appendix; review the draft against the TAC instructions before
finishing.
- Reference `web/src/api.ts` as the live field glossary for `Manifest`,
`SectionDoc`, `ViewDoc`, and `MetricTile`. Point to the live file rather than
duplicating its content, matching house convention.
- Add hard rules in the house tone: never invent maintainer-input values; never
invent numbers not present in a fetched document; cite the source section id and
dashboard link for every stated number.

Step 2 - Add the reference files:
- Place the TAC-question-to-API-section mapping file (from Phase 1) into
`.claude/skills/lfdt-report/`.
- Place the report-template and gap-appendix reference file (from Phase 1) into
`.claude/skills/lfdt-report/`.
- In `SKILL.md`, reference each reference file by relative path at the workflow
step that uses it.

Step 3 - Encode edge-case and error handling in the workflow:
- Add a step for the `mid-year` report type: select the mid-year skeleton and
its narrower question set.
- Add a step for orgs with absent macros: when the selected org's manifest entry
has no `sections`, `chart_sections`, or `views` for a macro (the `hiero-hackers`
case for Governance, HIPs, and Community), read `manifest.macro_absent_notes`
for the human-readable justification and record the absence in the report and
appendix. Do not emit a blank section.
- Add a step for an unreachable API: if `manifest.json` cannot be fetched, stop,
report the failure clearly, and produce no partial or fabricated draft.

Phase 3: Exercise, validate, and confirm zero code impact

This phase runs the skill against the live API and confirms the deliverable meets the ticket's "exercised, not just written" requirement. It also confirms the change is purely additive documentation.

Task 1: Generate and review the primary draft

Produce a real draft and review it against the TAC instructions.

Invoke the skill with report type annual and org hiero-ledger against the live API.
Review the draft against annual-review-instructions.md: confirm the five questions are present, data-backed sections carry real numbers with dashboard links, human-judgment slots are marked, and the Data Gaps appendix lists the expected gaps.
Save the reviewed draft as the committed sample under .claude/skills/lfdt-report/examples/ (Assumption 2), labeled as a point-in-time example, and attach it to the PR.

Task 2: Exercise the required edge cases

Confirm the skill behaves correctly on each edge case the ticket names.

Invoke the skill with report type mid-year and confirm it selects the mid-year structure.
Invoke the skill with org hiero-hackers and confirm it records the absent macros using macro_absent_notes rather than emitting blank sections.
Simulate or trigger an unreachable API and confirm the skill stops cleanly with a clear failure message and no fabricated content.
Attach the edge-case outputs and observations to the PR.

Task 3: Confirm zero code and contract impact

Verify the contribution is additive documentation only.

Confirm the change set touches only files under .claude/skills/lfdt-report/.
Confirm tests/contracts/test_output_contract.py and tests/contracts/test_readme_pipelines.py show zero diffs and no output-schema or pipeline-registry impact.
Confirm the skill prose recommends no layer-rule violations and references no pipeline names or chart filenames that do not already exist.

🤖 Prompt for AI agents

Implement Phase 3 by running the skill against the live API and confirming the
deliverable and its zero-code-impact status.

Step 1 - Generate and review the primary draft:
- Invoke the skill with report type `annual` and org `hiero-ledger` against the
live API.
- Review the draft against `annual-review-instructions.md`. Confirm the five
questions are present, confirm data-backed sections carry real numbers with
dashboard links, confirm human-judgment slots are marked, and confirm the Data
Gaps appendix lists the expected gaps.
- Save the reviewed draft as the committed sample under
`.claude/skills/lfdt-report/examples/`, label it as a point-in-time example, and
attach it to the PR.

Step 2 - Exercise the required edge cases:
- Invoke the skill with report type `mid-year` and confirm it selects the
mid-year structure.
- Invoke the skill with org `hiero-hackers` and confirm it records the absent
macros using `macro_absent_notes` instead of emitting blank sections.
- Simulate or trigger an unreachable API and confirm the skill stops cleanly
with a clear failure message and produces no fabricated content.
- Attach the edge-case outputs and observations to the PR.

Step 3 - Confirm zero code and contract impact:
- Confirm the change set touches only files under `.claude/skills/lfdt-report/`.
- Confirm `tests/contracts/test_output_contract.py` and
`tests/contracts/test_readme_pipelines.py` show zero diffs and no output-schema
or pipeline-registry impact.
- Confirm the skill prose recommends no layer-rule violations and references no
pipeline names or chart filenames that do not already exist.

Research

The repository publishes a versioned, static JSON data API under outputs/data/api/v1/ (served at https://hiero-hackers.github.io/analytics/data/api/v1/manifest.json). manifest.json lists, per org, arrays of sections, chart_sections, views, and metrics. Section and view documents are fetched by their path field. web/src/api.ts is the authoritative field glossary for these shapes (Manifest, SectionDoc, ChartSection, MatrixView, BoardView, MetricTile).

The existing skill .claude/skills/write-analytics-issue/SKILL.md is the house pattern: a single Markdown file with name+trigger description frontmatter, a stakes intro, and a numbered imperative workflow with hard gates.

The strict layer rules in docs/architecture.md and the contract tests in tests/contracts/ govern the Python code surface, but a .claude/skills/ Markdown file touches none of it.

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Implement Phase 1 as a research and design phase. Produce no skill prose yet;
produce the mapping reference and report template that later phases will encode
into the skill.

Step 1 - Capture the TAC report requirements:
- Read the live `LF-Decentralized-Trust/governance` directory
`tac/project-updates/`, in particular `annual-review-instructions.md` and
`mid-year-update-instructions.md`.
- Record the annual review's five questions: progress against last year's goals,
deliverables, next year's goals, help needed, and maintainer/contributor
diversity. Also record the supporting evidence categories: contribution
activity, adoption, and governance health.
- Record the mid-year update's questions: progress toward yearly goals, recent
deliverables, second-half goals, help needed, and changes in diversity.
- Record the file-naming and navigation conventions:
`tac/project-updates/<year>/YYYY-annual-Project-Name.md`,
`YYYY-MidYear-Project-Name.md`, and the `mkdocs.yml` navigation entry. Treat
these as output-format guidance for the skill to print.

Step 2 - Build the TAC-question-to-API-section mapping:
- Create a reference file in `.claude/skills/lfdt-report/` mapping each TAC
question and evidence item to the API macro(s) and section id(s) that supply it.
- Map maintainer/contributor diversity to `affiliations`,
`committeraffiliations`, `repodiversity`, `committerrepodiversity`,
`teamdiversity`, and the Governance metric tiles.
- Map governance-health evidence to `loadshare`, `gonedark`, `understaffed`, and
the Security `codeowners` section.
- Map adoption and roadmap evidence to `hip-no-activity`, `hip-evidence`,
`hip-unknown`, and views `hip-matrix`, `hip-board`.
- State explicitly that section documents carry `description`, not
`methodology`; `methodology` exists only on `ChartSpec.methodology` and
`MetricTile.methodology`. The skill must cite methodology only from metric tiles
and section descriptions, and treat chart-only methodology as a PNG-only gap.

Step 3 - Define the report template and gap appendix structure:
- Create a report-template reference file in `.claude/skills/lfdt-report/` with
annual and mid-year section skeletons derived from Step 1.
- Define the `> [MAINTAINER INPUT]` slot convention for human-judgment sections
(next year's / second-half goals, help needed); the skill must never invent
values for these slots.
- Define the Data Gaps appendix structure: one entry per missing fact, recording
the wanted fact, the TAC question it serves, the reason the API cannot supply it
(PNG-only chart, no JSON section, no query capability), and a follow-up pointer.
- Pre-seed the appendix with: contribution-activity trends over time
(chart-only), OpenSSF scorecard values (chart-only, never saved as CSV), "since
last report" deltas, and release staleness (cross-reference issue `#331`).
===============================================================================

Task: 2

Implement Phase 2 by writing the skill files that encode the Phase 1 design.

Step 1 - Write `.claude/skills/lfdt-report/SKILL.md`:
- Add YAML frontmatter with `name: lfdt-report` and a `description` that states
the skill's purpose and includes an explicit "Use whenever…" trigger clause for
drafting or refreshing an LFDT TAC report.
- Write a stakes intro that states the skill's dual purpose: draft the report,
and discover with evidence what the API layer is missing.
- Write a numbered imperative workflow with these steps in order: read the live
TAC instructions first; take inputs (report type `annual` | `mid-year`, org
default `hiero-ledger`); fetch `manifest.json` from the live API; walk the
`sections`, `views`, and `metrics` the manifest lists, with no hard-coded file
lists; map data to TAC questions using the mapping reference; fill data-backed
sections with real numbers and dashboard evidence links; render human-judgment
sections as `> [MAINTAINER INPUT]` slots; record every unfillable fact in the
Data Gaps appendix; review the draft against the TAC instructions before
finishing.
- Reference `web/src/api.ts` as the live field glossary for `Manifest`,
`SectionDoc`, `ViewDoc`, and `MetricTile`. Point to the live file rather than
duplicating its content, matching house convention.
- Add hard rules in the house tone: never invent maintainer-input values; never
invent numbers not present in a fetched document; cite the source section id and
dashboard link for every stated number.

Step 2 - Add the reference files:
- Place the TAC-question-to-API-section mapping file (from Phase 1) into
`.claude/skills/lfdt-report/`.
- Place the report-template and gap-appendix reference file (from Phase 1) into
`.claude/skills/lfdt-report/`.
- In `SKILL.md`, reference each reference file by relative path at the workflow
step that uses it.

Step 3 - Encode edge-case and error handling in the workflow:
- Add a step for the `mid-year` report type: select the mid-year skeleton and
its narrower question set.
- Add a step for orgs with absent macros: when the selected org's manifest entry
has no `sections`, `chart_sections`, or `views` for a macro (the `hiero-hackers`
case for Governance, HIPs, and Community), read `manifest.macro_absent_notes`
for the human-readable justification and record the absence in the report and
appendix. Do not emit a blank section.
- Add a step for an unreachable API: if `manifest.json` cannot be fetched, stop,
report the failure clearly, and produce no partial or fabricated draft.
===============================================================================

Task: 3

Implement Phase 3 by running the skill against the live API and confirming the
deliverable and its zero-code-impact status.

Step 1 - Generate and review the primary draft:
- Invoke the skill with report type `annual` and org `hiero-ledger` against the
live API.
- Review the draft against `annual-review-instructions.md`. Confirm the five
questions are present, confirm data-backed sections carry real numbers with
dashboard links, confirm human-judgment slots are marked, and confirm the Data
Gaps appendix lists the expected gaps.
- Save the reviewed draft as the committed sample under
`.claude/skills/lfdt-report/examples/`, label it as a point-in-time example, and
attach it to the PR.

Step 2 - Exercise the required edge cases:
- Invoke the skill with report type `mid-year` and confirm it selects the
mid-year structure.
- Invoke the skill with org `hiero-hackers` and confirm it records the absent
macros using `macro_absent_notes` instead of emitting blank sections.
- Simulate or trigger an unreachable API and confirm the skill stops cleanly
with a clear failure message and produces no fabricated content.
- Attach the edge-case outputs and observations to the PR.

Step 3 - Confirm zero code and contract impact:
- Confirm the change set touches only files under `.claude/skills/lfdt-report/`.
- Confirm `tests/contracts/test_output_contract.py` and
`tests/contracts/test_readme_pipelines.py` show zero diffs and no output-schema
or pipeline-registry impact.
- Confirm the skill prose recommends no layer-rule violations and references no
pipeline names or chart filenames that do not already exist.

💡 Iterate on the plan with: `@coderabbitai` <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

/assign

Thank you. Assigned
Note we are looking for new committers to the project, which will require a mix of intermediate skills regarding issue creation/triage/reviewing/committing skills.
We are in great need of review assistance!

@exploreriii

Hi @exploreriii I will help offer a hand on reviewing the PRs.

@exploreriii

Hi @exploreriii, my plan is a docs-only skill at .claude/skills/lfdt-report/SKILL.md, modeled on write-analytics-issue. It takes annual|mid-year and an org, fetches manifest.json, and walks the listed section docs (using web/src/api.ts as the field glossary) so new sections show up without edits. Data-backed sections get real numbers and dashboard links, goals and help-needed are [MANUAL INPUT] slots, and anything the API can't supply goes into a Data Gaps appendix. I'll run it for annual/hiero-ledger, mid-year, and hiero-hackers, and commit the outputs. No changes to code or the API. Does that fit what you had in mind?

@exploreriii

Hi @exploreriii, following up on my approach above. I've started a first draft of the skill and will keep going in the meantime, but wanted to check the plan still fits what you had in mind, especially the Data Gaps appendix and running it for annual, mid-year, and hiero-hackers. Happy to adjust if anything has changed. Thanks!

Yes but we have now got more thorough API access and the charts render dynamically, plus we have a printing functionality. Please do create the draft making sure the code is in line with main. Sounds great for a start! Thanks

@exploreriii

Hi @exploreriii Thanks for the update. I've opened a draft PR with the skill, written against current main (it uses the manifest, entity indexes and chart JSON, and does not rely on PNGs). I'm on the free Claude plan so I can't run it in Claude Code myself. I'll exercise it by following the steps by hand against the live API and attach the outputs, but if a maintainer can run it in Claude Code for annual, mid-year and hiero-hackers, that would be a better test. Which tool do you expect maintainers to use?

@exploreriii

Hello @exploreriii #523 is merged. It said "Part of" rather than "Closes", so this didn't auto-close. Is #439 done, or do you want a follow-up first (for example the content and efficiency refinements you mentioned, or the HTML sanitising CodeRabbit flagged for PDF export)? Happy to take either.

we should create more issues and refine the code :)

15. we should create more issues and refine the code :)

Yeah it will be great.

Navigation Menu

Repository navigation

Prototype a Claude skill that drafts Hiero's LFDT TAC report from the data API #439

The task

How to work on this

Coding Plan

Summary

Implementation Steps

Phase 1: Ground the design in the TAC instructions and the API contract

Phase 2: Author the skill

Phase 3: Exercise, validate, and confirm zero code impact

🚀 Next Steps

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Prototype a Claude skill that drafts Hiero's LFDT TAC report from the data API #439

Description

The task

How to work on this

Activity

coderabbitai commented on Aug 29, 2026

Coding Plan

Summary

Implementation Steps

Phase 1: Ground the design in the TAC instructions and the API contract

Phase 2: Author the skill

Phase 3: Exercise, validate, and confirm zero code impact

🚀 Next Steps

phillip-nyinomujuni commented on Sep 1, 2026

exploreriii commented on Sep 1, 2026

phillip-nyinomujuni commented on Sep 2, 2026

phillip-nyinomujuni commented on Sep 20, 2026

phillip-nyinomujuni commented on Sep 28, 2026

exploreriii commented on Sep 30, 2026

phillip-nyinomujuni commented on Oct 7, 2026

phillip-nyinomujuni commented on Oct 7, 2026

exploreriii commented on Oct 8, 2026

phillip-nyinomujuni commented on Oct 9, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions