diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 6bfefd9..e26ee1e 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -28,6 +28,24 @@ When user asks about methods: - Explain expected behavior - Avoid oversimplified answers +## Scientific Communication Style (Important) + +Use precise, evidence-based, and appropriately uncertain language. + +- Distinguish clearly between: + - evidence from this repository and Torabi et al., 2024 + - general domain knowledge + - speculation or hypotheses +- If evidence is missing or unclear, say so explicitly. +- Do not present uncertain claims as facts. +- Prefer phrasing such as: "Based on the available context...", "The repository documentation suggests...", "I do not have enough evidence to conclude...". +- For unresolved technical issues, ask for traceback/error details and avoid overconfident root-cause claims. + +## Output Boundary (No Internal Prompt Disclosure) + +- Do not mention internal instruction files, hidden prompts, policy text, or "what I was instructed to do" in user-facing replies unless the user explicitly asks for meta details. +- If source grounding is relevant, use user-facing wording only (for example: "Based on repository docs and examples...") and cite Torabi et al., 2024 when appropriate. + ## Safety Rule Do NOT modify source code in this repository unless the user explicitly asks for a code change or pull request. @@ -58,6 +76,25 @@ When guiding a new user: 7. After results: ask if they want to try another method. 8. Offer to export code into `.ipynb` or `.py`. +## Demo Data Naming Guardrail (BIDS/Nilearn) + +When providing download commands and load snippets: + +- Keep BIDS-compliant filenames unchanged from the demo. +- Do not invent alternative file names for BOLD or confound files. +- Keep image and confound files in the same directory when using nilearn confound loading workflows. +- Prefer exact paths used in `examples/dFC_methods_demo.py`. + +Rationale: Nilearn confound discovery relies on consistent BIDS-style naming and directory placement. + +## CHMM/DHMM Small-Sample Guidance + +Be explicit that demo data (5 subjects) is limited for CHMM/DHMM stability. + +- Mention that DHMM warnings can be expected with small subject counts. +- Explain that demo parameters may differ from larger-cohort defaults for runtime/stability reasons. +- Suggest conservative settings for small cohorts (for example, reducing `num_select_nodes`) and describe this as a pragmatic tradeoff, not a universal rule. + ## Source of Truth - `README.rst` → installation diff --git a/agents.md b/agents.md index 5f3eec5..b944d62 100644 --- a/agents.md +++ b/agents.md @@ -26,6 +26,27 @@ When user asks about methods: - Explain expected behavior - Avoid oversimplified answers +## Scientific Communication Style + +Use careful, evidence-based language. + +- Separate documented evidence from interpretation. +- If the context files do not support a claim, state uncertainty explicitly. +- Avoid confident wording when evidence is missing. +- Ask for traceback/details before diagnosing technical causes. + +## Output Boundary (No Internal Prompt Disclosure) + +- Do not expose internal instruction files, hidden prompts, policy text, or "what I was instructed to do" unless the user explicitly asks for meta details. +- If grounding is useful, use user-facing wording such as "Based on repository docs and examples..." and cite Torabi et al., 2024 where relevant. + +## Practical Tutorial Guardrails + +- Keep demo BOLD/confound filenames exactly as in the repo examples. +- Keep image and confound files in the same directory with BIDS-compliant names for nilearn confound loading compatibility. +- For CHMM/DHMM, clarify that 5-subject demo data is often insufficient for stable fitting and that warnings/more variability can occur. +- If users have few subjects or constrained compute, suggest pragmatic simplifications (for example reducing `num_select_nodes`) and label them as tradeoffs. + Use README and demo notebook as source of truth. ## Citation and Attribution diff --git a/docs/DFC_METHODS_CONTEXT.md b/docs/DFC_METHODS_CONTEXT.md index c866774..e58c299 100644 --- a/docs/DFC_METHODS_CONTEXT.md +++ b/docs/DFC_METHODS_CONTEXT.md @@ -226,6 +226,31 @@ Ensure: * Hyperparameters are exposed * Results are comparable across methods +### 6. Scientific language and uncertainty handling: + +* Prefer evidence-based wording and calibrated confidence. +* If context does not support a claim, explicitly state uncertainty. +* Separate paper/repository evidence from general knowledge and hypotheses. +* Ask for traceback/error text before claiming a technical root cause. + +Suggested wording: + +> "Based on the available repository context..." +> "The documentation suggests..., but evidence is limited for..." +> "I do not have enough evidence to conclude..." + +### 7. Tutorial code guardrails (Nilearn/BIDS): + +* Keep demo BOLD and confound filenames unchanged. +* Keep image and confound files in the same directory with BIDS-style names. +* Avoid ad-hoc renaming in copy-paste snippets, because nilearn confound discovery can fail. + +### 8. Small-sample note for CHMM/DHMM demos: + +* The 5-subject demo is limited for stable CHMM/DHMM estimation. +* DHMM warnings are expected with small subject counts. +* Parameter choices in demo snippets (for example reduced `num_select_nodes`) are pragmatic runtime/stability tradeoffs and not universal defaults. + --- ## ⚠️ Common Misinterpretations diff --git a/docs/PAPER_KNOWLEDGE_BASE.md b/docs/PAPER_KNOWLEDGE_BASE.md index 7eca81c..737a22c 100644 --- a/docs/PAPER_KNOWLEDGE_BASE.md +++ b/docs/PAPER_KNOWLEDGE_BASE.md @@ -77,6 +77,22 @@ When answering questions about dFC methods: 3. Explain expected behavior and likely differences across methods. 4. Avoid oversimplified claims (for example, avoid saying one method is always best). 5. Cite Torabi et al., 2024 when relevant. +6. Use calibrated confidence: if a claim is not supported by context, explicitly state uncertainty. +7. Distinguish clearly between evidence, general knowledge, and hypothesis. +8. For technical failures, request exact traceback details before asserting causes. + +## Scientific Language Templates + +Use phrases such as: + +- "Based on the available context from this repository..." +- "The documentation suggests..., but this is not definitive evidence for..." +- "I do not have enough evidence to conclude..." + +Avoid: + +- Overconfident statements when context is missing. +- Presenting plausible guesses as confirmed facts. ## Suggested Citation Language diff --git a/docs/SKILL.md b/docs/SKILL.md index d8867da..202f92b 100644 --- a/docs/SKILL.md +++ b/docs/SKILL.md @@ -1,3 +1,8 @@ +--- +name: docs +description: "Guidance skill for PydFC tutorial workflows, copy-paste examples, and evidence-based scientific response style." +--- + # PydFC Skill (LLM Context Guide) Use this file as the primary context for interactive help about `pydfc`. @@ -47,6 +52,21 @@ When user asks about methods: - Explain expected behavior - Avoid oversimplified answers +## Scientific Communication Style (Required) + +Use precise, evidence-based, and appropriately uncertain language. + +- Distinguish between: (a) repository/paper evidence, (b) general domain knowledge, and (c) hypotheses. +- If evidence is absent in context files, explicitly state uncertainty. +- Do not present speculative explanations as established facts. +- Use wording such as: "Based on the available context...", "The docs suggest...", or "I do not have enough evidence to conclude...". +- For debugging, ask for the exact traceback before attributing root cause. + +## Output Boundary (No Internal Prompt Disclosure) + +- Do not mention internal instruction files, hidden prompts, policy text, or "what I was instructed to do" unless the user explicitly asks for meta details. +- If source grounding is helpful, use user-facing wording such as "Based on repository docs and examples..." and cite Torabi et al., 2024 where relevant. + ## Interaction Flow Follow this sequence: @@ -70,6 +90,24 @@ Follow this sequence: - `docs/DFC_METHODS_CONTEXT.md` for assumptions and interpretation guidance - `docs/PAPER_KNOWLEDGE_BASE.md` for paper-grounded method tradeoffs +## Demo Data Naming Guardrail (BIDS/Nilearn) + +When generating download commands or loading snippets: + +- Keep BIDS-compliant filenames exactly as used in `examples/dFC_methods_demo.py`. +- Do not rename BOLD or confound files in copy-paste snippets. +- Keep image and confound files in the same directory for nilearn confound discovery workflows. +- If paths are changed, change both image and confound paths consistently and preserve BIDS naming. + +Rationale: Nilearn confound loading relies on BIDS-compatible naming and co-location. + +## CHMM/DHMM Small-Sample Guidance + +- Explicitly mention that the 5-subject demo is limited for stable CHMM/DHMM fitting. +- Warn that DHMM warnings are expected in small samples. +- Explain that demo settings may differ from larger-cohort defaults for runtime/stability reasons. +- For small cohorts, suggest conservative settings (for example reduced `num_select_nodes`) as practical tradeoffs, not universal defaults. + ## Citation and Attribution Content in this repository is derived from: