Tech Docs KB Search
Search technical and architectural documentation using AWS Bedrock Knowledge Base. Provides semantic and hybrid search over the lightspeed-hospitality/tech-docs corpus without needing a local clone.
Trigger
Use this skill when the user asks to:
- Find technical documentation, ADRs, RFCs, runbooks
- Understand service architecture or data flows
- Look up development guidelines or deployment procedures
- Run
/tech-docs
Prerequisites & Authentication
- AWS CLI v2 (
brew install awscli)
- granted CLI (
brew install common-fate/granted/granted)
- Access to the
lsk/dev/admin/eu-central-1 role
For prerequisite checks and SSO login flow, see references/auth.md.
IMPORTANT: Do NOT proceed with KB queries until credentials are confirmed working.
Configuration
| Parameter |
Value |
| Knowledge Base ID |
S3WJX83IGW |
| Data Source ID |
5OM2Q7H4CV |
| Region |
eu-central-1 |
| AWS Profile |
lsk/dev/admin/eu-central-1 |
| S3 Bucket |
s3://tech-docs-knowledge-base |
IMPORTANT: All aws commands must include --profile "lsk/dev/admin/eu-central-1" --region eu-central-1.
Indexed Content
| Area |
Content |
Architecture/ |
System architecture, fiscalization, data flows, service diagrams |
Decision-Records/ |
ADRs (0001-0018) and RFCs (0001-0079) |
Development/ |
Dev workflows, CI/CD, Signadot, deployment tooling, code quality |
How-We-Work/ |
Team processes, AI PR guidelines, on-call, service ownership |
Incidents/ |
Incident management, rollback procedures, debugging guides |
Infrastructure/ |
Kafka, Kubernetes, Elasticsearch, AWS, GCP, DR runbooks |
Projects/ |
POS, KDS, Fiscalization, AI Assistant, and 20+ other projects |
Tutorials/ |
How-to guides, datastore selection, and 15+ tutorial topics |
Onboarding/ |
New employee guides |
Learning/ |
Learning resources |
Not indexed: /blog content is intentionally excluded.
Search the Knowledge Base
Reformulate the Query
Do NOT pass the user's question verbatim. Extract key nouns and technical terms for HYBRID search:
| User question |
Good query |
| How does the POS blockchain work? |
POS blockchain device registration key generation block chaining signature verification |
| Why was GraphQL deprecated? |
GraphQL deprecation ADR REST migration Apollo Federation schema registry |
| What's the rollback procedure? |
ArgoCD rollback procedure SEV-0 incident revert PR |
Strategy: Include the topic, specific service/tool names, and 2-3 terms you'd expect in the answer document.
Run the Search
Always default to HYBRID search. It outperforms SEMANTIC-only in both precision and token efficiency.
aws bedrock-agent-runtime retrieve \
--knowledge-base-id S3WJX83IGW \
--retrieval-query '{"text": "QUERY"}' \
--retrieval-configuration '{"vectorSearchConfiguration": {"numberOfResults": 5, "overrideSearchType": "HYBRID"}}' \
--profile "lsk/dev/admin/eu-central-1" \
--region eu-central-1 \
--output json \
--no-cli-pager
| Query type |
Search type |
Results |
When |
| Default |
HYBRID |
5 |
Start here |
| Broad/cross-cutting |
HYBRID |
8 |
Answer spans multiple docs |
| Exact doc lookup |
HYBRID |
3 |
"Show me RFC-0063" |
| Fallback (scores < 0.3) |
SEMANTIC |
8 |
Only if HYBRID returns weak results |
For metadata filters and advanced search patterns, see references/advanced-search.md.
Handle Errors
- ExpiredTokenException / Invalid credentials: Re-run auth (see
references/auth.md), then retry
- AccessDeniedException: User may not have the required role
- ThrottlingException: Wait 3 seconds and retry once
Parse and Present Results
Evaluate Result Quality
| Top score |
Confidence |
Action |
| > 0.7 |
High |
3-5 results sufficient |
| 0.4 - 0.7 |
Medium |
Use all results, consider fetching full docs |
| < 0.4 |
Low |
Reformulate and retry |
| < 0.3 (all) |
Very low |
KB may not cover this topic |
Process Results
- Read chunks from
retrievalResults[].content.text
- Extract source paths from
retrievalResults[].location.s3Location.uri — strip bucket prefix to get repo-relative path
- For high-relevance results (score >= 0.4), fetch the full document from S3 — see
references/advanced-search.md
- Synthesize an answer — do NOT dump raw JSON or chunk text
- Cite sources with repo-relative file paths
Presentation Format
## [Topic]
[Synthesized answer from retrieved chunks and full documents]
**Sources:**
- `docs/path/to/file.md` — [what this doc covers]
Checklist
1---2name: tech-docs-kb3description: Search internal technical documentation, ADRs, RFCs, runbooks, architecture guides, and deployment procedures. Use when the user asks about how services work, project architecture, incident procedures, or development guidelines.4---5
6# Tech Docs KB Search
7
8Search technical and architectural documentation using AWS Bedrock Knowledge Base. Provides semantic and hybrid search over the `lightspeed-hospitality/tech-docs` corpus without needing a local clone.
9
10## Trigger
11
12Use this skill when the user asks to:
13- Find technical documentation, ADRs, RFCs, runbooks
14- Understand service architecture or data flows
15- Look up development guidelines or deployment procedures
16- Run `/tech-docs`
17
18## Prerequisites & Authentication
19
20- AWS CLI v2 (`brew install awscli`)
21- granted CLI (`brew install common-fate/granted/granted`)
22- Access to the `lsk/dev/admin/eu-central-1` role
23
24For prerequisite checks and SSO login flow, see `references/auth.md`.
25
26**IMPORTANT:** Do NOT proceed with KB queries until credentials are confirmed working.
27
28## Configuration
29
30| Parameter | Value |
31| --- | --- |
32| Knowledge Base ID | `S3WJX83IGW` |
33| Data Source ID | `5OM2Q7H4CV` |
34| Region | `eu-central-1` |
35| AWS Profile | `lsk/dev/admin/eu-central-1` |
36| S3 Bucket | `s3://tech-docs-knowledge-base` |
37
38**IMPORTANT:** All `aws` commands must include `--profile "lsk/dev/admin/eu-central-1" --region eu-central-1`.
39
40### Indexed Content
41
42| Area | Content |
43| --- | --- |
44| `Architecture/` | System architecture, fiscalization, data flows, service diagrams |
45| `Decision-Records/` | ADRs (0001-0018) and RFCs (0001-0079) |
46| `Development/` | Dev workflows, CI/CD, Signadot, deployment tooling, code quality |
47| `How-We-Work/` | Team processes, AI PR guidelines, on-call, service ownership |
48| `Incidents/` | Incident management, rollback procedures, debugging guides |
49| `Infrastructure/` | Kafka, Kubernetes, Elasticsearch, AWS, GCP, DR runbooks |
50| `Projects/` | POS, KDS, Fiscalization, AI Assistant, and 20+ other projects |
51| `Tutorials/` | How-to guides, datastore selection, and 15+ tutorial topics |
52| `Onboarding/` | New employee guides |
53| `Learning/` | Learning resources |
54
55**Not indexed:** `/blog` content is intentionally excluded.
56
57## Search the Knowledge Base
58
59### Reformulate the Query
60
61Do NOT pass the user's question verbatim. Extract key nouns and technical terms for HYBRID search:
62
63| User question | Good query |
64| --- | --- |
65| How does the POS blockchain work? | `POS blockchain device registration key generation block chaining signature verification` |
66| Why was GraphQL deprecated? | `GraphQL deprecation ADR REST migration Apollo Federation schema registry` |
67| What's the rollback procedure? | `ArgoCD rollback procedure SEV-0 incident revert PR` |
68
69**Strategy:** Include the topic, specific service/tool names, and 2-3 terms you'd expect in the answer document.
70
71### Run the Search
72
73Always default to **HYBRID** search. It outperforms SEMANTIC-only in both precision and token efficiency.
74
75```bash
76aws bedrock-agent-runtime retrieve \
77 --knowledge-base-id S3WJX83IGW \
78 --retrieval-query '{"text": "QUERY"}' \
79 --retrieval-configuration '{"vectorSearchConfiguration": {"numberOfResults": 5, "overrideSearchType": "HYBRID"}}' \
80 --profile "lsk/dev/admin/eu-central-1" \
81 --region eu-central-1 \
82 --output json \
83 --no-cli-pager
84```
85
86| Query type | Search type | Results | When |
87| --- | --- | --- | --- |
88| Default | `HYBRID` | 5 | Start here |
89| Broad/cross-cutting | `HYBRID` | 8 | Answer spans multiple docs |
90| Exact doc lookup | `HYBRID` | 3 | "Show me RFC-0063" |
91| Fallback (scores < 0.3) | `SEMANTIC` | 8 | Only if HYBRID returns weak results |
92
93For metadata filters and advanced search patterns, see `references/advanced-search.md`.
94
95### Handle Errors
96
97- **ExpiredTokenException / Invalid credentials**: Re-run auth (see `references/auth.md`), then retry
98- **AccessDeniedException**: User may not have the required role
99- **ThrottlingException**: Wait 3 seconds and retry once
100
101## Parse and Present Results
102
103### Evaluate Result Quality
104
105| Top score | Confidence | Action |
106| --- | --- | --- |
107| > 0.7 | High | 3-5 results sufficient |
108| 0.4 - 0.7 | Medium | Use all results, consider fetching full docs |
109| < 0.4 | Low | Reformulate and retry |
110| < 0.3 (all) | Very low | KB may not cover this topic |
111
112### Process Results
113
1141. Read chunks from `retrievalResults[].content.text`
1152. Extract source paths from `retrievalResults[].location.s3Location.uri` — strip bucket prefix to get repo-relative path
1163. For high-relevance results (score >= 0.4), fetch the full document from S3 — see `references/advanced-search.md`
1174. Synthesize an answer — do NOT dump raw JSON or chunk text
1185. Cite sources with repo-relative file paths
119
120### Presentation Format
121
122```
123## [Topic]
124
125[Synthesized answer from retrieved chunks and full documents]
126
127**Sources:**
128- `docs/path/to/file.md` — [what this doc covers]
129```
130
131## Checklist
132
133- [ ] Verified AWS CLI v2 and active credentials before searching
134- [ ] Reformulated the query (extracted key terms, not verbatim)
135- [ ] Used HYBRID search as default
136- [ ] Actually ran the `aws` command using the Bash tool
137- [ ] Evaluated result scores and retried if top score < 0.4
138- [ ] Fetched full documents from S3 for high-relevance results
139- [ ] Synthesized an answer (not raw dump)
140- [ ] Cited source document paths
majiayu000