Open
Conversation
Contributor
📝 WalkthroughWalkthroughThis PR introduces comprehensive documentation infrastructure for an agent role system. It adds four new roles (Prompt Engineer, Product Owner, GitHub Actions Engineer, Neon Database Engineer) and establishes an extensive knowledge library covering best practices, competencies, frameworks, methodologies, deliverables, engagement models, collaboration patterns, and operational skills. Changes
Possibly related PRs
Poem
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes 🚥 Pre-merge checks | ✅ 2 | ❌ 1❌ Failed checks (1 inconclusive)
✅ Passed checks (2 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
📝 Coding Plan for PR comments
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 4
🧹 Nitpick comments (4)
.agents/_library/methodologies/prompt-development-lifecycle.md (1)
1-8: Consider expanding each lifecycle stage with more detail.The six stages are well-structured and cover the essential flow of prompt development. However, the document is quite brief. Each stage could optionally be expanded with:
- Concrete examples or techniques
- Key deliverables or artifacts
- Common pitfalls to avoid
- Links to related tools or best practices
This would transform the document from a quick reference into actionable guidance for practitioners.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.agents/_library/methodologies/prompt-development-lifecycle.md around lines 1 - 8, Expand each of the six lifecycle stages (Requirements Analysis, Initial Design, Iterative Refinement, Edge Case Handling, Documentation, Monitoring & Maintenance) by adding 2–4 concrete items per stage: at least one short real-world example or technique, key deliverables/artifacts to produce, common pitfalls to avoid, and 1–2 recommended tools or best-practice links; update the Prompt Development Lifecycle section so each numbered stage becomes a brief subsection containing those bullets to turn the note into actionable guidance..agents/skills/github-issue-management/references/gh-issue-commands.md (1)
72-77: Replace thergdependency withghnative JSON filtering for better portability.Lines 75–76 assume
rgis available, but the setup section (lines 5–18) never declares this dependency. All other commands in the file use onlygh. This creates an unnecessary portability gap.Use
gh's native JSON output withjqinstead:Suggested patch
-gh label list --repo "$OWNER/$REPO" --limit 200 | rg "^epic\\b" || \ -gh label create epic --repo "$OWNER/$REPO" --color "5319e7" --description "Container issue for larger initiatives" +gh label list --repo "$OWNER/$REPO" --json name --jq '.[] | select(.name == "epic") | .name' | grep -qx 'epic' || \ +gh label create epic --repo "$OWNER/$REPO" --color "5319e7" --description "Container issue for larger initiatives"🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.agents/skills/github-issue-management/references/gh-issue-commands.md around lines 72 - 77, Replace the external ripgrep usage in the label existence check by using gh's JSON filtering instead: update the check that currently pipes gh label list into rg to instead call gh label list with JSON output and gh's --jq or equivalent JSON selector to test for a label named "epic", then fall back to the existing gh label create command if not found; modify the command that invokes gh label list (the snippet referencing "epic" and gh label create) to use gh's native JSON/--jq filtering so no external rg dependency is required..agents/_library/frameworks/evaluation-framework.md (1)
5-13: Add an explicit factuality/grounding dimension.For agent and prompt work,
Functional+Consistencystill misses the “sounds right but is wrong” case. A dedicated row for factual accuracy / grounding would make this framework safer to apply.Suggested tweak
| Dimension | Question | | ------------------- | ------------------------------------------------------- | | **Functional** | Does it achieve the intended outcome? | +| **Factuality** | Are claims grounded in provided inputs, tools, or sources? | | **Robustness** | How does it handle edge cases and unexpected inputs? | | **Consistency** | Are outputs stable across multiple runs? | | **Efficiency** | Is resource usage (time, cost, effort) optimized? | | **Safety** | Are potential misuse vectors addressed with guardrails? | | **Maintainability** | Can it be easily understood, updated, and extended? | | **Documentation** | Is usage clear and well-documented? |🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.agents/_library/frameworks/evaluation-framework.md around lines 5 - 13, Add a new evaluation dimension row to the markdown table for factuality/grounding (e.g., "Factuality / Grounding") to capture "sounds right but is wrong" failures; update the table between "Consistency" and "Efficiency" (or next to "Safety") and use a clear question like "Are outputs factually correct and properly grounded to verifiable sources?" so reviewers can assess grounding separately from Functional and Consistency..agents/_library/competencies/output-quality-control.md (1)
6-6: Clarify that validation should not rely on self-checks alone.
Self-verificationcan help, but on its own it often just restates the same mistake more confidently. I'd tighten this to mention tool-backed or source-backed validation explicitly.Suggested wording
-- **Validation Patterns:** Building self-verification and error-checking into prompt flows +- **Validation Patterns:** Combining self-checks with tool-backed, schema-based, or source-backed validation in prompt flows🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.agents/_library/competencies/output-quality-control.md at line 6, Update the "Validation Patterns" bullet so it clarifies that self-verification alone is insufficient: edit the line containing "Validation Patterns" / the phrase "self-verification" to explicitly state that validation should be backed by external tools or authoritative sources (e.g., tool-backed or source-backed validation) rather than relying solely on internal self-checks; keep the existing wording but append a short clause recommending corroboration with external tools/sources.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In @.agents/_library/best-practices/neon-database.md:
- Around line 7-8: Replace the absolute rule "never hand-write migration SQL"
with a softer guideline that recommends using `drizzle-kit generate` after
schema changes but allows reviewed manual edits when a change cannot be safely
represented by the schema diff; also correct the incorrect claim about generator
behavior by explicitly stating that `drizzle-kit generate` diffs the latest
snapshot and appends a new migration without modifying previously generated
files (i.e., it does not rewrite existing migration SQL). Target the bullet
containing "never hand-write migration SQL" and the sentence referencing
`drizzle-kit generate` to update wording accordingly.
In @.agents/_library/competencies/neon-database-engineering.md:
- Line 8: Update the migration tooling bullet to mark `drizzle-kit push` as
non-production only: modify the line that currently lists "drizzle-kit generate,
drizzle-kit migrate, drizzle-kit push" (the Migration tooling entry) to note
that `drizzle-kit push` should be used only in non-production environments and
that production deployments should use the generate->migrate flow; ensure the
wording mirrors the companion best-practices guidance for consistency.
In @.agents/roles/github-actions-engineer.md:
- Around line 89-91: The relative link "[Cross-Functional
Collaboration](../_library/collaboration/cross-functional.md)" in
.agents/roles/github-actions-engineer.md is stale; update the href to point to
the new file name "../_library/collaboration/cross-functional-teams.md" so the
link resolves to the added collaboration doc (look for the link text
"Cross-Functional Collaboration" in that markdown and replace the target
filename).
In @.agents/roles/neon-database-engineer.md:
- Around line 46-50: Update the section to explicitly document the mapping
between environment variables across layers: state that BRANCH_DB_URL (used by
preview branches and resolved in db.ts via the invariant check) should map to
Vercel/CI preview env var (e.g., DATABASE_URL or a preview-specific
DATABASE_URL), DEFAULT_DB_URL maps to the production/dev fallback DATABASE_URL,
and DATABASE_URL_UNPOOLED is the direct/unpooled connection used for
migrations/Drizzle operations; reference the db.ts invariant logic and the
preview branch naming (preview/pr-{number}-{branch}) and also apply the same
clarification to the text at lines 71-72 so readers know which var to use in app
code vs CI/Vercel plugin/migration scripts.
---
Nitpick comments:
In @.agents/_library/competencies/output-quality-control.md:
- Line 6: Update the "Validation Patterns" bullet so it clarifies that
self-verification alone is insufficient: edit the line containing "Validation
Patterns" / the phrase "self-verification" to explicitly state that validation
should be backed by external tools or authoritative sources (e.g., tool-backed
or source-backed validation) rather than relying solely on internal self-checks;
keep the existing wording but append a short clause recommending corroboration
with external tools/sources.
In @.agents/_library/frameworks/evaluation-framework.md:
- Around line 5-13: Add a new evaluation dimension row to the markdown table for
factuality/grounding (e.g., "Factuality / Grounding") to capture "sounds right
but is wrong" failures; update the table between "Consistency" and "Efficiency"
(or next to "Safety") and use a clear question like "Are outputs factually
correct and properly grounded to verifiable sources?" so reviewers can assess
grounding separately from Functional and Consistency.
In @.agents/_library/methodologies/prompt-development-lifecycle.md:
- Around line 1-8: Expand each of the six lifecycle stages (Requirements
Analysis, Initial Design, Iterative Refinement, Edge Case Handling,
Documentation, Monitoring & Maintenance) by adding 2–4 concrete items per stage:
at least one short real-world example or technique, key deliverables/artifacts
to produce, common pitfalls to avoid, and 1–2 recommended tools or best-practice
links; update the Prompt Development Lifecycle section so each numbered stage
becomes a brief subsection containing those bullets to turn the note into
actionable guidance.
In @.agents/skills/github-issue-management/references/gh-issue-commands.md:
- Around line 72-77: Replace the external ripgrep usage in the label existence
check by using gh's JSON filtering instead: update the check that currently
pipes gh label list into rg to instead call gh label list with JSON output and
gh's --jq or equivalent JSON selector to test for a label named "epic", then
fall back to the existing gh label create command if not found; modify the
command that invokes gh label list (the snippet referencing "epic" and gh label
create) to use gh's native JSON/--jq filtering so no external rg dependency is
required.
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 43045d3b-cb2e-40df-b64f-6d3be882f387
📒 Files selected for processing (40)
.agents/AGENTS.md.agents/_library/best-practices/github-actions.md.agents/_library/best-practices/neon-database.md.agents/_library/best-practices/product-ownership.md.agents/_library/best-practices/prompt-engineering.md.agents/_library/collaboration/cross-functional-teams.md.agents/_library/collaboration/prompt-engineering-teams.md.agents/_library/competencies/agile-delivery.md.agents/_library/competencies/backlog-management.md.agents/_library/competencies/discovery-validation.md.agents/_library/competencies/github-actions-engineering.md.agents/_library/competencies/llm-understanding.md.agents/_library/competencies/neon-database-engineering.md.agents/_library/competencies/output-quality-control.md.agents/_library/competencies/product-vision.md.agents/_library/competencies/prompt-architecture.md.agents/_library/competencies/stakeholder-management.md.agents/_library/deliverables/github-actions-deliverables.md.agents/_library/deliverables/neon-database-deliverables.md.agents/_library/deliverables/product-artifacts.md.agents/_library/deliverables/prompt-engineering.md.agents/_library/engagement-models/consulting-engagement.md.agents/_library/engagement-models/product-engagement.md.agents/_library/frameworks/evaluation-framework.md.agents/_library/frameworks/invest-criteria.md.agents/_library/frameworks/product-metrics-kpis.md.agents/_library/frameworks/prompt-engineering-techniques.md.agents/_library/frameworks/user-story-format.md.agents/_library/methodologies/prioritization-frameworks.md.agents/_library/methodologies/product-development-lifecycle.md.agents/_library/methodologies/prompt-development-lifecycle.md.agents/_library/output-standards/prompt-output-standards.md.agents/_library/tools/prompt-development-tools.md.agents/roles/github-actions-engineer.md.agents/roles/neon-database-engineer.md.agents/roles/product-owner.md.agents/roles/prompt-engineer.md.agents/skills/follow-up-ticket-hardening/SKILL.md.agents/skills/github-issue-management/SKILL.md.agents/skills/github-issue-management/references/gh-issue-commands.md
Comment on lines
+7
to
+8
| - Generate migrations with `drizzle-kit generate` after every schema change — never hand-write migration SQL | ||
| - Keep migration files small and single-concern — one logical change per migration |
Contributor
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
# First, locate and read the file mentioned in the review
cat -n .agents/_library/best-practices/neon-database.mdRepository: hypha-dao/hypha-web
Length of output: 3121
🏁 Script executed:
# Search for any other references to drizzle-kit in the codebase for context
rg "drizzle-kit|migration" --type md -B 2 -A 2Repository: hypha-dao/hypha-web
Length of output: 11945
🌐 Web query:
drizzle-kit generate migration behavior how it handles existing migrations
💡 Result:
drizzle-kit generate is codebase-first and does not look at your database to decide what to generate. Instead it: reads your existing local migration history (the previous migration folders / snapshots), diffs that “previous schema state” against your current TypeScript schema, may prompt for renames, then writes a brand-new migration (SQL + a new snapshot) to disk. It does not rewrite or re-number existing migrations; it just appends a new one when there’s a diff. [1]
How “existing migrations” affect generation:
- Baseline = latest local snapshot/migration state: the newest snapshot in your migrations directory is treated as the “old schema” for diffing. If you delete/alter old migration folders/snapshots, you can change what Drizzle thinks the baseline is (and therefore what it generates). [1], [2]
- Folder format matters: newer Drizzle Kit uses the “v3” migrations layout (one folder per migration, containing
snapshot.json+migration.sql) and removed the oldjournal.jsonapproach to reduce git conflicts; older projects can be upgraded withdrizzle-kit up. [2] - Branch/team conflicts are possible if different branches generate migrations from different “latest snapshots”; Drizzle has been evolving tooling/approaches around this (e.g., migration structure changes and later commutativity/conflict detection work). [2], [3]
Related (execution vs generation): drizzle-kit migrate is the step that reads migration.sql files, checks what’s applied in the DB, then applies only unapplied migrations. [1]
Sources:
[1] Drizzle ORM docs – Migrations (generate/migrate flow, “read previous migration folders”, diff, write new migration) (orm.drizzle.team)
[2] Drizzle ORM v1.0.0-beta.2 release notes – v3 folder structure, drizzle-kit up, removal of journal.json (orm.drizzle.team)
[3] GitHub discussion – v3 folder structure details, generation based on newest snapshot and related concerns (github.com)
Citations:
- 1: https://orm.drizzle.team/docs/migrations
- 2: https://orm.drizzle.team/docs/latest-releases/drizzle-orm-v1beta2
- 3: Migrations folder structure v3 drizzle-team/drizzle-orm#2832
Soften the migration SQL rule — guidance is overstated and partially incorrect.
Line 7's "never hand-write migration SQL" is too absolute; reviewed manual edits are valid when a change cannot be expressed safely from the schema diff alone. More critically, line 24 is factually incorrect: drizzle-kit generate does not rewrite existing migration files. It reads the latest migration snapshot, diffs the current schema, and appends a new migration without modifying previously generated SQL. Manual edits to migration files will not be overwritten by subsequent generate calls.
Suggested wording
- - Generate migrations with `drizzle-kit generate` after every schema change — never hand-write migration SQL
+ - Generate migrations with `drizzle-kit generate` after every schema change — review the generated SQL and only hand-edit when the change cannot be expressed safely from the schema diff alone
...
- - Hand-editing generated migration SQL — changes will be overwritten on next `drizzle-kit generate`
+ - Hand-editing generated migration SQL without documenting why — keep manual edits rare, reviewed, and consistent with the schema snapshotAlso applies to: 24-24
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In @.agents/_library/best-practices/neon-database.md around lines 7 - 8, Replace
the absolute rule "never hand-write migration SQL" with a softer guideline that
recommends using `drizzle-kit generate` after schema changes but allows reviewed
manual edits when a change cannot be safely represented by the schema diff; also
correct the incorrect claim about generator behavior by explicitly stating that
`drizzle-kit generate` diffs the latest snapshot and appends a new migration
without modifying previously generated files (i.e., it does not rewrite existing
migration SQL). Target the bullet containing "never hand-write migration SQL"
and the sentence referencing `drizzle-kit generate` to update wording
accordingly.
| - **Platform:** Neon — serverless Postgres with autoscaling, branching, and instant restore | ||
| - **Driver:** `@neondatabase/serverless` — WebSocket-based connection pooling for edge/serverless runtimes | ||
| - **ORM:** Drizzle ORM (`drizzle-orm/neon-serverless`) with typed schema definitions and relational queries | ||
| - **Migration tooling:** `drizzle-kit generate` (schema diffing), `drizzle-kit migrate` (apply), `drizzle-kit push` (direct schema sync) |
Contributor
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
# Find the competency file and related best-practices docs
find . -type f -name "*neon*" -o -name "*best-practice*" -o -name "*guideline*" | head -20Repository: hypha-dao/hypha-web
Length of output: 371
🏁 Script executed:
# Search for references to drizzle-kit push and production in the repository
rg "drizzle-kit push" -A 3 -B 3Repository: hypha-dao/hypha-web
Length of output: 545
🏁 Script executed:
# Look for best-practices or guidelines files in the .agents directory
find .agents -type f -name "*.md" | grep -E "(best-practice|guideline|guide)" | head -20Repository: hypha-dao/hypha-web
Length of output: 413
🏁 Script executed:
# Read the best-practices doc to verify the claim about drizzle-kit push
cat .agents/_library/best-practices/neon-database.mdRepository: hypha-dao/hypha-web
Length of output: 2876
🏁 Script executed:
# Also read the competency doc to confirm the current state of line 8
cat .agents/_library/competencies/neon-database-engineering.mdRepository: hypha-dao/hypha-web
Length of output: 3483
Add a non-production caveat for drizzle-kit push.
Line 8 lists push alongside the safer generate/migrate flow, but the companion best-practices doc explicitly forbids it for production deployments. Adding a non-production restriction here keeps guidance consistent and prevents unsafe command selection.
Suggested wording
- - **Migration tooling:** `drizzle-kit generate` (schema diffing), `drizzle-kit migrate` (apply), `drizzle-kit push` (direct schema sync)
+ - **Migration tooling:** `drizzle-kit generate` (schema diffing), `drizzle-kit migrate` (apply), `drizzle-kit push` (direct schema sync for development/prototyping only; not production)📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| - **Migration tooling:** `drizzle-kit generate` (schema diffing), `drizzle-kit migrate` (apply), `drizzle-kit push` (direct schema sync) | |
| - **Migration tooling:** `drizzle-kit generate` (schema diffing), `drizzle-kit migrate` (apply), `drizzle-kit push` (direct schema sync for development/prototyping only; not production) |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In @.agents/_library/competencies/neon-database-engineering.md at line 8, Update
the migration tooling bullet to mark `drizzle-kit push` as non-production only:
modify the line that currently lists "drizzle-kit generate, drizzle-kit migrate,
drizzle-kit push" (the Migration tooling entry) to note that `drizzle-kit push`
should be used only in non-production environments and that production
deployments should use the generate->migrate flow; ensure the wording mirrors
the companion best-practices guidance for consistency.
Comment on lines
+89
to
+91
| ## Collaboration | ||
|
|
||
| [Cross-Functional Collaboration](../_library/collaboration/cross-functional.md) |
Contributor
There was a problem hiding this comment.
Fix the stale collaboration link.
Line 91 appears to point at the wrong file. The collaboration library added in this PR is cross-functional-teams.md, so this relative link likely 404s as written.
Suggested fix
- [Cross-Functional Collaboration](../_library/collaboration/cross-functional.md)
+ [Cross-Functional Collaboration](../_library/collaboration/cross-functional-teams.md)📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| ## Collaboration | |
| [Cross-Functional Collaboration](../_library/collaboration/cross-functional.md) | |
| ## Collaboration | |
| [Cross-Functional Collaboration](../_library/collaboration/cross-functional-teams.md) |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In @.agents/roles/github-actions-engineer.md around lines 89 - 91, The relative
link "[Cross-Functional
Collaboration](../_library/collaboration/cross-functional.md)" in
.agents/roles/github-actions-engineer.md is stale; update the href to point to
the new file name "../_library/collaboration/cross-functional-teams.md" so the
link resolves to the added collaboration doc (look for the link text
"Cross-Functional Collaboration" in that markdown and replace the target
filename).
Comment on lines
+46
to
+50
| - **Connection resolution:** `BRANCH_DB_URL` (preview) → `DEFAULT_DB_URL` (production/dev fallback) — enforced via `invariant` check in `db.ts` | ||
| - **Schema architecture:** One schema file per entity (`space.ts`, `document.ts`, `people.ts`, `membership.ts`, `tokens.ts`, `transfers.ts`, `event.ts`, `flags.ts`, `categories.ts`) with separate `.relations.ts` files for join definitions | ||
| - **Migration pipeline:** `drizzle-kit generate` diffs schema → SQL migration files in `migrations/` → applied by `drizzle-kit migrate` in CI and `drizzle-kit push` for local dev | ||
| - **Branching strategy:** Preview branches (`preview/pr-{number}-{branch}`) created per PR, migrations applied before deployment, schema diff posted as PR comment, branch deleted on PR close | ||
| - **Vercel integration:** Neon Postgres via Vercel Marketplace — `DATABASE_URL` (pooled), `DATABASE_URL_UNPOOLED` (direct) injected per environment; preview-specific vars injected at deployment time by webhook |
Contributor
There was a problem hiding this comment.
Document how the env-var names map across layers.
This section mixes BRANCH_DB_URL / DEFAULT_DB_URL with DATABASE_URL / DATABASE_URL_UNPOOLED but never explains the translation between them. Without that mapping, the agent can easily recommend the wrong variable name for app code vs. CI/Vercel setup.
Also applies to: 71-72
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In @.agents/roles/neon-database-engineer.md around lines 46 - 50, Update the
section to explicitly document the mapping between environment variables across
layers: state that BRANCH_DB_URL (used by preview branches and resolved in db.ts
via the invariant check) should map to Vercel/CI preview env var (e.g.,
DATABASE_URL or a preview-specific DATABASE_URL), DEFAULT_DB_URL maps to the
production/dev fallback DATABASE_URL, and DATABASE_URL_UNPOOLED is the
direct/unpooled connection used for migrations/Drizzle operations; reference the
db.ts invariant logic and the preview branch naming
(preview/pr-{number}-{branch}) and also apply the same clarification to the text
at lines 71-72 so readers know which var to use in app code vs CI/Vercel
plugin/migration scripts.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary by CodeRabbit
New Features
Documentation