Merge pull request #50 from mtorabi59/main

giving AI-assisstant a more scientifique language

Author: mtorabi59

.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

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

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

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
 

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: