Skip to content

README.md

Latest commit

 

History

History
138 lines (111 loc) · 13.8 KB

README.md

File metadata and controls

138 lines (111 loc) · 13.8 KB

.github/prompts/ — Agentic Workflow Prompt Library

This directory holds the bounded-context prompt modules imported by every news workflow in .github/workflows/news-*.md. It replaces the previous monolithic .github/aw/SHARED_PROMPT_PATTERNS.md.

Why

  • One concern per module — each file is ≤ 300 lines and has a single responsibility.
  • Explicit dependencies — workflows declare imports in YAML frontmatter (imports:), not by prose reference.
  • No duplication — modules link to the canonical methodology, template, and MCP config files rather than copy them.
  • No audit history — rules only, no dated run IDs, PR numbers, or version tags.

Integration points (authoritative)

This directory is the single source of truth for how GitHub Agentic Workflows (gh-aw) produce news articles in this repo. Agents, skills, and copilot instructions MUST link back here rather than restate the rules.

  • gh-aw runtime: github/gh-aw-actions/setup@v0.74.3 (SHA-pinned in every news-*.lock.yml; MCP Gateway image ghcr.io/github/gh-aw-mcpg:v0.3.9; setup-cli variant used only by agentics-maintenance.yml).
  • Upstream documentation — link-out only, never copy content:
  • Article-generation system map → Article-Generation.md is the readable end-to-end contract for how workflows, prompts, artifacts, article.md, renderer chrome, SEO, UI/UX exports, and deployment fit together. Prompt modules below remain the executable per-phase rules.
  • Analysis artifact contract (the "deep political analysis" product that every news workflow must produce before writing a single article sentence):
    • Read-me-first — analysis/methodologies/artifact-catalog.md (single source of truth for every artifact — family, template, depth floor, Mermaid, MCP, gate check) and analysis/methodologies/per-artifact-methodologies.md (Inputs / Analytic-moves / Evidence-rules / Anti-patterns per artifact)
    • Methodology → analysis/methodologies/ai-driven-analysis-guide.md
    • Indicator maps → worldbank-indicator-mapping.md (non-economic WB) + imf-indicator-mapping.md (authoritative IMF for all economic context)
    • Depth floors → reference-quality-thresholds.json (per-article-type × per-artifact line floors, tradecraft signals)
    • Templates → analysis/templates/ (one file per artifact — 23 always-on + per-document + 7 operational supplementary)
    • 23 required artifacts (every workflow, produced in analysis/daily/$ARTICLE_DATE/$SUBFOLDER/): Family A Core Synthesis — README.md, executive-brief.md, synthesis-summary.md, significance-scoring.md, classification-results.md, swot-analysis.md, risk-assessment.md, threat-analysis.md, stakeholder-perspectives.md; Family B Structural Metadata — data-download-manifest.md, cross-reference-map.md; Family C Strategic Extensions (F3EAD Exploit→Analyze) — scenario-analysis.md, comparative-international.md, devils-advocate.md, intelligence-assessment.md, methodology-reflection.md ⭐; Family D Electoral & Domain Lenses — election-2026-analysis.md, voter-segmentation.md, coalition-mathematics.md, historical-parallels.md, media-framing-analysis.md, implementation-feasibility.md, forward-indicators.md. Plus Family E per-document documents/{dok_id}-analysis.md. Full definitions in 04-analysis-pipeline.md.
    • 7 operational supplementary artifacts (not counted in the 23; recommended for deep, mandatory for comprehensive / Tier-C): analysis-index.md, reference-analysis-quality.md, mcp-reliability-audit.md, workflow-audit.md, cross-run-diff.md, cross-session-intelligence.md, session-baseline.md.
    • 4 analytical supplementary artifacts (never blocking, optional deep-dives): pestle-analysis.md, political-stride-assessment.md, wildcards-blackswans.md, quantitative-swot.md. Full rules in analytical-supplementary-methodology.md.
    • Tier-C aggregation produces the same 23 artifacts plus depth multipliers, cross-type sibling-folder citations, prior-cycle PIR ingestion, and a 1 500-word article floor — see ext/tier-c-aggregation.md.
  • Single blocking gate: 05-analysis-gate.md is the only enforcer. No article may be touched until the gate passes.
  • AI-FIRST rule (from 00-base-contract.md §Non-negotiable rules #5): minimum 2 complete iterations — Pass 1 creates every artifact, Pass 2 reads Pass 1 back in full and improves every section.

Module catalogue

File Responsibility Consumed by
00-base-contract.md Role, ethics, GDPR/ISMS, AI-FIRST quality rule, pipeline order All news workflows + translate
01-bash-and-shell-safety.md Bash tool call format, AWF-safe shell patterns, UTF-8 All news workflows + translate
02-mcp-access.md MCP server inventory, tool naming, in-prompt health gate All news workflows + translate
03-data-download.md Download pipeline, subfolder naming, lookback fallback, manifest All content workflows
04-analysis-pipeline.md Methodologies, templates, 23 required artifacts (Families A+B+C+D), Pass 1 / Pass 2 All content workflows
05-analysis-gate.md Single blocking gate before any article is touched (checks 1–9 across all 23 artifacts; supplementary check 9 is blocking for comprehensive / Tier-C / multi-run) All content workflows
06-article-generation.md Article sections, banned patterns, visualisation, translations All content workflows
07-commit-and-pr.md Stage → commit → exactly one create_pull_request All news workflows + translate
seo-metadata-contract.md Reference contract for <title> + <meta description> per language (used at render time, not imported) Reference document — referenced by 06-article-generation.md and the renderer
ext/tier-c-aggregation.md Tier-C additive rules: period multipliers, cross-type sibling synthesis, prior-cycle PIR ingestion, article floor Aggregation & reference-grade workflows
ext/long-horizon-forecasting.md Long-horizon additive rules on top of Tier-C: horizon stratification, scenario-tree depth, counterfactual mandate, IMF projection-year stamps, PESTLE blocking thresholds, cross-horizon citation news-week-ahead, news-month-ahead, news-quarter-ahead, news-year-ahead, news-election-cycle
ext/cycle-rollover.md Election cycle file-rename + carry-forward + PIR archival procedure (active only within ± 30 days of a Swedish election anchor) news-election-cycle (no-op outside ± 30-day window)

Dependency matrix

Workflow 00 01 02 03 04 05 06 07 tier-c long-horizon cycle-rollover
news-propositions ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
news-motions ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
news-committee-reports ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
news-interpellations ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
news-evening-analysis ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
news-week-ahead ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ (recommended)
news-month-ahead ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ (recommended)
news-quarter-ahead ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
news-year-ahead ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
news-election-cycle ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
news-weekly-review ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
news-monthly-review ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
news-realtime-monitor ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
news-translate ✅ ✅ ✅ ✅

Phase sequence (single-run workflow)

flowchart LR
  A[Download data<br/>module 03] --> B[Read methodologies &amp; templates<br/>module 04]
  B --> C[Analysis Pass 1<br/>module 04]
  C --> D[Analysis Pass 2<br/>module 04]
  D --> E{Analysis Gate<br/>module 05}
  E -- pass --> F[Aggregate analysis → article.md<br/>module 06]
  E -- fail --> G[Fix &amp; retry]
  G --> E
  F --> H[Render article.md → HTML × 14 languages<br/>module 06]
  H --> I[Stage &amp; commit<br/>module 07]
  I --> J[ONE create_pull_request<br/>module 07]
  style A fill:#0a0e27,stroke:#00d9ff,color:#e0e0e0
  style E fill:#1a1e3d,stroke:#ff006e,color:#e0e0e0
  style J fill:#1a1e3d,stroke:#ffbe0b,color:#e0e0e0
Loading

Translations for the remaining twelve languages are produced inside the same per-type agentic run (see 06-article-generation.md §"Step 2 — Translate article.md"). The dedicated news-translate workflow runs three times a day on a separate track and is responsible only for the executive-brief markdown pipeline — translating analysis/daily/**/executive-brief.md into executive-brief_<lang>.md for the 13 non-English target languages (see .github/workflows/news-translate.md and TRANSLATION_GUIDE.md §"Executive Brief Markdown Translations").

Why multiple prompt imports (not a single Copilot Agent File)

gh-aw supports two distinct import styles:

Style Source Per-workflow cap Frontmatter shape Use for
Plain imports Any .md outside .github/agents/ unlimited plain Markdown (no special frontmatter required) Shared rule modules — this directory.
Copilot Agent File .github/agents/<name>.md exactly one per workflow name, description, tools, mcp-servers Per-issue delegation via assign_copilot_to_issue, or a single specialised persona for one workflow.

News workflows need eight bounded-context modules (role, shell, MCP, download, analysis, gate, article, commit) plus an optional Tier-C extension. The "one agent file per workflow" limit makes that infeasible as a single agent file, so we use plain imports. The 24 files under .github/agents/ remain the persona catalogue for assign_copilot_to_issue and for any future workflow that genuinely needs a single reusable persona per run.

If a workflow ever needs a single reusable persona (e.g. a pure code-review workflow), that workflow may import one agent file from .github/agents/ in addition to any plain prompt imports — gh-aw allows mixing the two styles.

Authoring rules for new / edited modules

Rule Enforced by
≤ 300 lines per module CI check in compile-agentic-workflows.yml
No audit history, PR/run IDs, version tags Code review
Link to canonical external docs rather than copy content Code review
Tables over prose where rules are enumerable Code review
Declarative ("do X") not narrative ("we decided to do X because of PR #1794") Code review

Changing the import list of a workflow

  1. Edit the workflow's frontmatter imports: list.
  2. Run gh aw compile locally.
  3. Commit both .md and regenerated .lock.yml.

See .github/skills/github-agentic-workflows/SKILL.md §"Imports" for gh-aw import semantics.

History

The monolithic .github/aw/SHARED_PROMPT_PATTERNS.md was deleted when these modules went live. Every rule from the old file was either migrated into one of the modules above, merged with an equivalent rule, or deleted as audit history / duplicated content / tutorial from a skill file.

Related directory READMEs