AIOPS-04] Build a prompt engineering library and skill development practice

[paruff]

[AIOPS-04] Build a prompt engineering library and skill development practice

Labels: ai-ops, documentation, p1-critical, effort-medium
Assignee: 👤 Human (library authoring) + 🤖 Copilot (tooling)
Phase: Phase 1 — AI Foundation
DORA 2025 Source: “Prompt engineering is rising as a core developer skill” finding (p. 88 sociocognitive impact section)
Effort: Medium (1–2 days to build; ongoing maintenance)
Prerequisites: AIOPS-01, AIOPS-02

---

Why This Is a New Requirement from 2025 DORA

The 2025 DORA report identifies prompt engineering as an emerging core developer skill — one that reshapes career paths and team dynamics. The report is explicit: “The modern engineer’s value is in prompt engineering, solution architecture and validating AI-generated outputs — not just in writing code.”

AIOPS-02 created TDD prompt templates. This issue goes further: it builds a reusable, versioned library of prompts for all the repeating task types in Goald’s development cycle, and establishes the practice of prompt improvement as a team discipline (not just an individual habit).

The 2025 report also warns that without structured prompt practices, AI adoption creates fragmented, inconsistent results that increase — rather than reduce — cognitive load.

---

What the Prompt Library Covers

Category	Prompts to Include
TDD	New utility function, new service method, bug fix (already in AIOPS-02 — reference here)
Security	Security review of a service function, Firestore rules review, auth flow review
Code review	“Review this PR diff against our copilot-instructions.md”
Refactoring	Extract inline logic to a utility, consolidate duplicate components
Debugging	“Explain why this Firestore query throws permission-denied”, “Why does this useEffect fire twice”
Architecture	“Does this component belong in screens/ or components/? Explain using our file structure”
Documentation	Generate JSDoc for this function, update DATA_MODEL.md for this new field

---

Acceptance Criteria

Prompt Library File

• docs/PROMPT_LIBRARY.md created with sections for each category above
• Each prompt entry includes:
  • Task type — what you’re trying to accomplish
  • Context to include — what to paste alongside the prompt (e.g., the function signature, the test file, the copilot-instructions.md section)
  • Prompt template — with {{placeholders}} for variable parts
  • Expected output shape — what a good Copilot response looks like
  • Red flags — signs the output is wrong (e.g., “if Copilot calls Firestore directly in a component, reject and re-prompt with rule 3 from copilot-instructions.md”)

Prompt Review Cadence

• Monthly PROCESS-02 tuning checklist updated to include: “Did any prompt produce repeated bad output this month? Update the prompt template.”
• docs/PROMPT_LIBRARY.md has a ## Changelog section at the bottom

VS Code Snippet Integration

• .vscode/goald-prompts.code-snippets created with the most-used prompts as VS Code snippets
• Documented in README.md under “AI-Assisted Development” — “Type goald- in VS Code to access prompt snippets”

Example Prompt (Security Review)

## Security Review Prompt

**Context to include:** The full service function + src/types/index.ts + the "Security Rules" section of .github/copilot-instructions.md

**Prompt:**
Review the following service function for security issues. Apply these rules from our project:
1. All Firestore reads/writes must be scoped to the authenticated user's userId
2. No raw Firebase error messages should be surfaced to the UI
3. All numeric inputs must be validated as finite, positive numbers before any write
4. No `any` types in catch blocks — use the typed error pattern from src/utils/errors.ts

Function to review:
{{PASTE FUNCTION HERE}}

For each issue found, provide: the exact line, the risk, and the corrected code.

**Expected output shape:** A numbered list of findings with severity (Critical / Warning / Info) and corrected code snippets.

**Red flag:** If Copilot returns "no issues found" for a function that uses `catch (e: any)`, the review missed something — re-prompt with the specific rule.

---

Files to Create

• docs/PROMPT_LIBRARY.md
• .vscode/goald-prompts.code-snippets
• Update docs/TDD_PROMPTS.md — add cross-reference to PROMPT_LIBRARY.md
• Update .github/copilot-instructions.md — add “See docs/PROMPT_LIBRARY.md for task-specific prompt templates”
• Update README.md — add “AI-Assisted Development” section