source-attribution

name	source-attribution
description	Adds source citations to responses indicating which documentation files provided the information, or indicates if response is from general context. Use this whenever providing guidance to ensure transparency and traceability.

Source Attribution

Purpose

Ensure all agent responses transparently cite the source of information being provided, distinguishing between documentation, skills, and general knowledge.

When to Use

Apply this automatically when:

• Providing guidance about coding patterns
• Recommending specific implementations
• Explaining framework behavior
• Reference architecture or workflows
• Quoting conventions or standards

Documentation Sources in TAF

Framework Documentation:

• AGENTS.md - Framework purpose, commands, repository layout, development patterns
• README.md - Setup instructions, environment requirements, execution commands
• docs/architecture.humans.md - Component architecture, module boundaries, runtime flows
• docs/architecture.agents.md - Agent-optimized architecture with data contracts and validation clues
• docs/agent-context/repo-inventory.md - Detailed component breakdown
• docs/agent-context/build-test-matrix.md - Execution commands by component
• docs/agent-context/domain-glossary.md - Couchbase and TAF terminology
• docs/agent-context/troubleshooting.md - Common issues and solutions
• docs/agent-context/data-service/AGENTS.md - KV/Data Service specific guidance
• docs/agent-context/ns-server/AGENTS.md - NS Server/Cluster Manager specific guidance

Citation Format

For documentation sources:

[from <file-path>]
[from <file-path>, section: <section-name>]
[from AGENTS.md, section: Repository Layout]
[from docs/architecture.agents.md, section: Test Execution Layer]

For skills:

[from agents/<skill-name>/SKILL.md]
[from .factory/skills/<skill-name>/SKILL.md]

For general knowledge:

[from general context]
[from general Python best practices]
[from standard testing frameworks patterns]
[from generic common knowledge]

Examples

Example 1: Repository Structure

To add a new test for bucket operations:

1. Create test file in pytests/bucket_collections/
2. Inherit from OnPremBaseTest (from AGENTS.md, section: Test Execution Model)
3. Use TestInputSingleton.input.param() for parameters (from AGENTS.md, section: Configuration Files)
4. Follow PEP8 standards (from general context)

Example 2: Test Execution

Run tests using:
python testrunner.py -i node.ini -c conf/sanity.conf (from AGENTS.md, section: Quick Commands)

For individual tests:
python testrunner.py -i node.ini -t epengine.basic_ops.basic_ops.test_doc_size (from AGENTS.md)

Example 3: Architecture Guidance

The testrunner.py initializes the cluster via:
1. Loads cluster configuration from node.ini (from docs/architecture.agents.md, section: Runtime Flow Diagram)
2. Selects base test class based on runtype parameter (from AGENTS.md, section: Test Execution Model)
3. Executes tests with parameters from .conf files (from general context)

Rules

• Always cite when referencing specific framework behavior, patterns, or conventions
• Cite the most specific source - if info is in both AGENTS.md and docs/architecture.agents.md, cite the more detailed one
• Use section citations when documentation is long to help users verify
• Distinguish TAF-specific from general programming knowledge
• Be honest if citing general context - don't falsely attribute to documentation
• Cite multiple sources when relevant, separated by semicolons

Detection Heuristics

Cite documentation when:

• Explaining TAF-specific directory structure or file locations
• Describing test execution patterns or frameworks
• Reference build commands or test commands
• Discussing component interactions or architecture
• Explaining configuration file formats
• Mentioning repository-specific conventions

Use "general context" when:

• Providing Python best practices (PEP8, etc.)
• Explaining standard testing patterns
• Discussing general software engineering principles
• Providing vanilla Python code examples
• Giving generic debugging advice not specific to TAF

Response Pattern

When responding, automatically include citations inline or at the end:

Your guidance here (from AGENTS.md, section: X)

Multiple sentences here, each with source attribution (from docs/architecture.agents.md)
More details (from general context)

Validation

After providing a response, verify:

• All TAF-specific information has a source citation
• General context is clearly marked as such
• Citations point to actual documentation that exists
• Section names are accurate (if using section citations)