diff --git a/ProblemMap/Atlas/Fixes/templates/prompt-template.md b/ProblemMap/Atlas/Fixes/templates/prompt-template.md index 87053926..8fa09c28 100644 --- a/ProblemMap/Atlas/Fixes/templates/prompt-template.md +++ b/ProblemMap/Atlas/Fixes/templates/prompt-template.md @@ -36,7 +36,135 @@ Reading discipline for AI: AI_NOTE_END --> -# Prompt Template +# Prompt Template 🧩 + +## Problem Map 3.0 Troubleshooting Atlas +## Reusable template for prompt-based fix contributions + +Quick links: + +- [Back to Templates Hub](./README.md) +- [Back to Contribution Checklist](./contribution-checklist.md) +- [Back to Fix Recipe Template](./fix-recipe-template.md) +- [Back to Community Fix Lab](../community/README.md) +- [Back to Official Fixes](../official/README.md) +- [Back to Atlas landing page](../../../wfgy-ai-problem-map-troubleshooting-atlas.md) +- [Back to Atlas Hub](../../README.md) +- [Open Colab Template](./colab-template.md) +- [Get the Atlas Router TXT](../../troubleshooting-atlas-router-v1.txt) + +--- + +This file is the reusable template for writing a clean prompt-based fix contribution. + +If the **Fix Recipe Template** helps you document a repair asset broadly, this template helps you document **prompt-based repair assets** in a smaller, more testable, and more reusable form ✨ + +Use this template when you want to submit: + +- one prompt-based repair asset +- one route-aware prompt intervention +- one trace, repair, or evaluation prompt +- one prompt that supports a clearly defined first move + +The goal is not to dump prompts. + +The goal is to keep prompt contributions: + +- routed +- scoped +- testable +- reviewable +- honest about limits + +--- + +## Quick start 🚀 + +Use this template in the following order: + +1. fill **Title** +2. fill **0. Quick summary** +3. fill **1. Prompt type** +4. fill **2. Atlas routing context** +5. fill **3. Problem this prompt addresses** +6. fill **4. Intended use** +7. fill **6. Prompt body** +8. fill **7. Expected output shape** +9. fill **8. First repair connection** +10. fill **9. Misrepair warning** +11. add optional sections only if relevant +12. finish with **13. Files included** and **14. One-line maintainer note** + +If you want the fastest possible start, jump to: + +- **15. Copy-paste mini skeleton** + +Short version: + +> one prompt +> one clear use stage +> one first repair connection +> one misrepair warning 📌 + +--- + +## Required vs optional quick map 🗂️ + +| Section | Status | Purpose | +|---|---|---| +| Title | Required | identify the prompt contribution clearly | +| 0. Quick summary | Required | explain what the prompt does | +| 1. Prompt type | Required | classify the main prompt role | +| 2. Atlas routing context | Required | anchor the prompt in atlas logic | +| 3. Problem this prompt addresses | Required | define the target problem | +| 4. Intended use | Required | show when and where to use the prompt | +| 5. Inputs expected by the prompt | Required | show what the prompt needs | +| 6. Prompt body | Required | provide the actual prompt | +| 7. Expected output shape | Required | define what good output looks like | +| 8. First repair connection | Required | connect the prompt to first repair logic | +| 9. Misrepair warning | Required | prevent bad prompt use | +| 10. Optional evaluation notes | Optional | add useful checks only if they help | +| 11. Optional WFGY escalation | Optional | only if deeper bridge is relevant | +| 12. Limitations | Recommended | keep the contribution honest | +| 13. Files included | Required | make the submission reviewable | +| 14. One-line maintainer note | Required | help quick review | + +--- + +## A good prompt contribution usually looks like this 🌱 + +A strong prompt contribution usually has: + +- one family +- one clear problem +- one main prompt role +- one intended use stage +- one expected output shape +- one first repair connection +- one misrepair warning + +Small and focused beats broad and overloaded almost every time. + +--- + +## Important prompt discipline 🔒 + +A prompt contribution should not try to do everything at once. + +If one prompt is trying to do: + +- routing +- first repair +- evaluation +- escalation +- and final solution generation + +all in one block, it is usually too broad. + +Choose the **main prompt role first**. +Add other prompt roles only if they clearly support the same contribution. + +--- ## Title @@ -59,7 +187,7 @@ It is meant for F5-first cases where diagnosability is too weak to support confi ## 1. Prompt type -Choose one or more: +Choose one or more, but choose the **main prompt role first**. - system prompt - user prompt @@ -69,9 +197,15 @@ Choose one or more: - trace-exposure prompt - WFGY escalation prompt +If your contribution mixes several prompt roles, make it clear which one is the main asset and which ones are supporting blocks. + --- -## 2. Atlas routing context +## 2. Atlas routing context ⭐ + +This is one of the most important sections in the whole template. + +A prompt without routing context is much harder to review and much easier to misuse. **Primary family** `F?` @@ -105,7 +239,7 @@ Keep this short and concrete. --- -## 4. Intended use +## 4. Intended use ⭐ State clearly how this prompt should be used. @@ -128,6 +262,9 @@ Optional format: **Target environment** `...` +This section matters because a good prompt is not only about wording. +It is also about timing and placement. + --- ## 5. Inputs expected by the prompt @@ -146,15 +283,15 @@ Examples: Use a short format like: -```text +~~~text Input A: Input B: Input C: -```` +~~~ --- -## 6. Prompt body +## 6. Prompt body ⭐ Paste the actual prompt here. @@ -162,63 +299,71 @@ Recommended format: ### System prompt -```text +~~~text ... -``` +~~~ ### User prompt -```text +~~~text ... -``` +~~~ If only one prompt is needed, include only one block. +Keep this section focused. +If the prompt body tries to handle too many jobs at once, the contribution is usually too broad. + --- -## 7. Expected output shape +## 7. Expected output shape ⭐ Describe what a good output should look like. Examples: -* clearer routing justification -* better trace exposure -* cleaner first repair recommendation -* fewer unsupported claims -* more structured schema-preserving output +- clearer routing justification +- better trace exposure +- cleaner first repair recommendation +- fewer unsupported claims +- more structured schema-preserving output Optional format: **Expected structure** -```text +~~~text ... -``` +~~~ **Expected improvement** -```text +~~~text ... -``` +~~~ + +This is one of the most reviewer-important sections. +A prompt without an expected output shape is much harder to validate. --- -## 8. First repair connection +## 8. First repair connection ⭐ Explain how this prompt supports the official first repair move. Useful questions: -* what first move does this prompt reinforce -* what family-level fix surface does it support -* why is prompt intervention appropriate here +- what first move does this prompt reinforce +- what family-level fix surface does it support +- why is prompt intervention appropriate here -Keep it short. +Keep it short and concrete. + +This section is one of the clearest signals that the prompt is a real atlas-aligned fix asset, not just an isolated prompt snippet. --- -## 9. Misrepair warning +## 9. Misrepair warning ⭐ This section is required. @@ -244,19 +389,21 @@ If useful, list a few simple checks. Examples: -* better support rate -* clearer stage localization -* fewer lost fields -* fewer wrong anchors -* higher schema pass rate +- better support rate +- clearer stage localization +- fewer lost fields +- fewer wrong anchors +- higher schema pass rate Optional format: -```text +~~~text Metric 1: Metric 2: Metric 3: -``` +~~~ + +Only include fields that are actually useful. --- @@ -270,10 +417,10 @@ Use this only if the prompt is meant to bridge into deeper WFGY work. ### What should be passed into WFGY -* routed family -* broken invariant -* first repair already attempted -* unresolved pressure +- routed family +- broken invariant +- first repair already attempted +- unresolved pressure ### What WFGY is expected to add @@ -289,11 +436,11 @@ Be honest. Examples: -* only tested on short prompts -* only tested in one model family -* not suitable for long multi-agent traces -* helps diagnosis, not full repair -* still experimental +- only tested on short prompts +- only tested in one model family +- not suitable for long multi-agent traces +- helps diagnosis, not full repair +- still experimental Short, honest limits are much better than inflated claims. @@ -305,9 +452,9 @@ List the files included in the contribution. Example: -* `prompt.md` -* `example_input.json` -* `expected_output.md` +- `prompt.md` +- `example_input.json` +- `expected_output.md` --- @@ -315,16 +462,16 @@ Example: Write one short line that helps review the contribution. -Example: +Example: Small F5 prompt for improving trace visibility before deeper intervention. --- -## 15. Copy-paste mini skeleton +## 15. Copy-paste mini skeleton ✂️ Use this when you want the fastest possible start. -````md +~~~md # Title ## 0. Quick summary @@ -359,42 +506,55 @@ Target environment: ... ## 7. Expected output shape - ... ## 8. First repair connection - ... ## 9. Misrepair warning - Wrong first move: Why it is tempting: Why this prompt should not be used that way: ## 10. Optional evaluation notes - ... ## 11. Optional WFGY escalation - ... ## 12. Limitations - ... ## 13. Files included - ... ## 14. One-line maintainer note - ... +~~~ -``` -```` +--- +## Next steps ✨ + +After this page, most readers continue with: + +1. [Back to Contribution Checklist](./contribution-checklist.md) +2. [Back to Templates Hub](./README.md) +3. [Back to Fix Recipe Template](./fix-recipe-template.md) +4. [Open Colab Template](./colab-template.md) + +If you want to return to the broader product surface: + +- [Back to Community Fix Lab](../community/README.md) +- [Back to Official Fixes](../official/README.md) +- [Back to Atlas landing page](../../../wfgy-ai-problem-map-troubleshooting-atlas.md) +- [Back to Atlas Hub](../../README.md) + +If this template helps your workflow, consider: + +- [starring the WFGY repo](https://github.com/onestardao/WFGY) +- opening an issue +- shipping one small clean prompt contribution 🌟 ---