feat(docs): Add prompting guideline #427
Open
Conversation
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
This commit introduces a new documentation page, "Prompting Guideline," which provides comprehensive instructions and best practices for interacting with Pochi. The new guide covers: - General prompting strategies. - How to craft clear, structured, and effective prompts. - Task-specific examples for various development workflows like debugging, refactoring, and feature development. Additionally, the documentation's navigation (meta.json) has been updated to include this new page under the "Resources" section. 🤖 Generated with [Pochi](https://getpochi.com) Co-Authored-By: Pochi <[email protected]>
🤖 Generated with [Pochi](https://getpochi.com) Co-Authored-By: Pochi <[email protected]>
- Corrected invalid frontmatter syntax. - Escaped special characters causing MDX parsing failures. - Fixed malformed XML example block. 🤖 Generated with [Pochi](https://getpochi.com) Co-Authored-By: Pochi <[email protected]>
|
jinsyl123
changed the title
wsxiaoys
requested changes
Sep 26, 2025
jinsyl123
force-pushed
the
docs/add-prompting-guideline
branch
from
cddf368 to
4c64953
Compare
- Clarified the meaning of 'structure' in prompts to refer to structured formats like XML or JSON. - Corrected and expanded the 'Leverage Pochi Features' section to be more accurate and readable, detailing the specific files and directories for rules, workflows, and custom agents based on verified documentation. 🤖 Generated with [Pochi](https://getpochi.com) Co-Authored-By: Pochi <[email protected]>
gyxlucy
reviewed
Sep 28, 2025
Adds relevant links to the prompting guideline documentation for features like the CLI, rules, workflows, custom agents, and integrations. Also clarifies the language around sharing features to avoid confusion. 🤖 Generated with [Pochi](https://getpochi.com) Co-Authored-By: Pochi <[email protected]>
jinsyl123
force-pushed
the
docs/add-prompting-guideline
branch
from
20b7fa0 to
26f8ac7
Compare
gyxlucy
reviewed
Oct 1, 2025
|
Hi @wsxiaoys I have already made changes for the doc, do give me your feedback on it! |
wsxiaoys
requested changes
Oct 3, 2025
| **Example:** | ||
| “Debug `@main.py`: Identify the null reference issue in `fetchUser()`, propose a fix, test with `pytest test_main.py`, log the result." | ||
|
|
||
| ### Use Structured Prompts |
There was a problem hiding this comment.
this is more of a prompting skills for AI app developer (like us), not for our end user.
Comment on lines
+89
to
+94
| ### Assign Pochi a Role (System Prompts) | ||
|
|
||
| Specify a role in the prompt or via a [custom agent](/custom-agent) to enforce standards. | ||
|
|
||
| **Example:** | ||
| “Act as linter for `@models/db.py` per `README.pochi.md`, focusing on PEP 8 spacing issues.” |
There was a problem hiding this comment.
this example doesn't show case custom agent. and README.pochi.md doesn't really need explicit reference
Comment on lines
+96
to
+101
| ### Chain Complex Prompts | ||
|
|
||
| Divide large tasks into numbered steps for manageability. | ||
|
|
||
| **Example:** | ||
| “Step 1: Review `@api.py` for existing `/users` route, Step 2: Add `/users` GET endpoint with Flask-Login authentication.” |
There was a problem hiding this comment.
the example for this would best be https://github.com/snarktank/ai-dev-tasks, and Pochi actually adopt it in https://github.com/TabbyML/pochi/tree/main/.pochi/workflows
(create-pr / generate-tasks / process-tasks)
wsxiaoys
reviewed
Oct 3, 2025
Comment on lines
+103
to
+118
| ## Task-Specific Applications | ||
|
|
||
| This section applies prompting patterns to common development workflows, from project management to optimization. Customize these templates for your stack. | ||
|
|
||
| ### Project Management | ||
|
|
||
| - **Initiating a New Project Phase:** “Start a new phase for `@api.js`: Initialize a `/auth` module, list dependencies, document setup separately.” | ||
| - **Reviewing Recent Changes:** “Review `@api.js`: Summarize last 3 commits’ impact on `/users`, flag issues.” | ||
| - **Syncing Team Context:** “Sync `@utils.js` changes: Compile a summary of edits across `@api.js` and `@utils.js`, share via [Pochi link](/share), align with standards.” | ||
|
|
||
| ### Debugging | ||
|
|
||
| - **Analyzing a Crash:** “Analyze `@main.py`: Investigate why `fetchUser()` crashes with null, suggest fix, test with `pytest`.” | ||
| - **Handling Concurrency Issues:** “Debug `@main.py`: Identify deadlock in `fetchUser()` under 50 calls, propose lock fix, validate with `pytest --concurrency=5`.” | ||
| - **Handling a 500 Error:** “Handle `@api.js`: Diagnose a 500 error on `/users`, suggest a fallback, test with mock data.” | ||
| - **Handling an API Fetch Error:** “Debug `@frontend.js`: Fix a fetch error from external API, suggest retry logic (e.g., `setTimeout`), test with mock delay.” |
There was a problem hiding this comment.
to reader, this entire session is more of a showcase on how to use @ feature to attach file.
wsxiaoys
reviewed
Oct 3, 2025
|
|
||
| ### Assign Pochi a Role (System Prompts) | ||
|
|
||
| Specify a role in the prompt or via a [custom agent](/custom-agent) to enforce standards. |
There was a problem hiding this comment.
use code-reviewer / ask agent as example
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
4 participants
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.
#481
Summary
This PR introduces a new Prompting Guideline document to the official Pochi documentation. It also includes several critical fixes that were required to resolve build failures caused by syntax errors in the new MDX file.
New Documentation: Prompting Guideline
The new
prompting-guideline.mdxpage provides a comprehensive guide for users on how to write effective prompts for Pochi. It covers:Fixes Implemented
cant---->---) that was preventing the MDX parser from reading the file's metadata.<character in a code example to prevent it from being parsed as an HTML tag.<file>tags..pochi/agents/andrules/) instead ofREADME.pochi.md.Additional Enhancements
Based on further review feedback, the following improvements have been made:
Test Plan
The local development server (
bun run dev) is used for visual checks and live previews. The production build (bun run build) is a more thorough check to ensure the site can be deployed.bun run buildwithin thepackages/docsdirectory to confirm all build errors are resolved.bun run devand visually confirmed that the new "Prompting Guideline" page renders correctly without errors. https://screen.studio/share/vy62uJVB🤖 Generated with Pochi